Skip to main content
rpc-admin is a command-line utility for managing API keys used by sol-rpc-router. All keys are stored in Redis and support per-key rate limiting, owner tracking, and active/inactive status.

​
Global Options

​
--redis-url
string
default:"redis://127.0.0.1:6379"
Redis connection URL. Can also be set via REDIS_URL environment variable.
rpc-admin --redis-url redis://localhost:6379/0 list

​
Commands

​
create

Create a new API key with configurable rate limits and optional expiration. 
rpc-admin create <owner> [OPTIONS]
​
owner
string
required
Owner identifier for the key (e.g., client-name, project-id). Used for tracking and metrics.
​
--rate-limit
number
default:"10"
Rate limit in requests per second (RPS).
​
--expires-at
number
Expiration timestamp (Unix epoch seconds). Optional.
​
--key
string
Custom API key value. If omitted, a random 32-character alphanumeric key is generated.

​
Examples

# Create key with default rate limit (10 RPS)
rpc-admin create my-client

# Create key with custom rate limit
rpc-admin create my-client --rate-limit 50

# Create key with expiration (expires at 2025-12-31 23:59:59 UTC)
rpc-admin create my-client --rate-limit 100 --expires-at 1735689599

# Create key with custom value
rpc-admin create my-client --rate-limit 10 --key my-custom-key-12345

​
Output

Created API key for my-client:
aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
Redis Storage

Keys are stored as Redis hashes with the following structure: 
HSET api_key:aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
  owner "my-client"
  rate_limit 10
  created_at 1709481600
  active "true"
  expires_at 1735689599  # optional

SADD api_keys_index aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
list

List all API keys with owner and active status. 
rpc-admin list

​
Example Output

Found 3 keys:
- aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 [owner=my-client] [active=true]
- xYz789AbCdEfGhIjKlMnOpQrStUvWx12 [owner=project-alpha] [active=true]
- qWeRtYuIoPaSdFgHjKlZxCvBnM987654 [owner=old-client] [active=false]

​
inspect

View detailed information about a specific API key. 
rpc-admin inspect <key>
​
key
string
required
The API key to inspect.

​
Example

rpc-admin inspect aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
Output

Key: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
Owner: my-client
Active: true
Rate Limit: 50 RPS
Created At: 1709481600
If the key doesn’t exist: 
Key not found

​
revoke

Revoke an API key by marking it as inactive. The key remains in Redis but authentication will fail. 
rpc-admin revoke <key>
​
key
string
required
The API key to revoke.

​
Example

rpc-admin revoke aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
Output

Revoked key: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
Or if the key doesn’t exist: 
Key not found: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
Implementation Details

Revocation sets the active field to "false" in Redis: 
HSET api_key:aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 active "false"
The key remains in the api_keys_index set and can be reactivated using the update command.

​
update

Update properties of an existing API key. 
rpc-admin update <key> [OPTIONS]
​
key
string
required
The API key to update.
​
--rate-limit
number
New rate limit in requests per second.
​
--owner
string
New owner identifier.
​
--active
boolean
Set to true to activate or false to deactivate the key.

​
Examples

# Update rate limit
rpc-admin update aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 --rate-limit 100

# Reactivate a revoked key
rpc-admin update aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 --active true

# Update owner name
rpc-admin update aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 --owner new-client-name

# Update multiple properties
rpc-admin update aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 --rate-limit 100 --active true

​
Output

Updated key: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
  rate_limit -> 100
  active -> true
If no options are provided: 
No changes requested for key: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
If the key doesn’t exist: 
Key not found: aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

​
Environment Variables

​
REDIS_URL
string
default:"redis://127.0.0.1:6379"
Alternative to --redis-url flag. The flag takes precedence if both are set.
export REDIS_URL="redis://localhost:6379/0"
rpc-admin list

​
Redis Key Schema

​
API Key Hash

Each API key is stored as a Redis hash at api_key:<key_value>:
FieldTypeDescription
ownerstringOwner identifier
rate_limitnumberRequests per second limit
created_atnumberUnix timestamp of creation
activestring"true" or "false"
expires_atnumberOptional Unix timestamp

​
Index Set

All keys are tracked in a Redis set: 
SMEMBERS api_keys_index
# Returns: ["key1", "key2", "key3", ...]
This set is used by the list command to enumerate all keys efficiently.

​
Caching Behavior

API keys are cached in the router’s memory for 60 seconds to reduce Redis load. This means:
  • Key updates may take up to 60 seconds to take effect across all router instances
  • Revoked keys may continue to work for up to 60 seconds
  • Rate limit changes are applied on the next cache miss (maximum 60 seconds)
If immediate enforcement is required, restart the router.
The caching behavior includes:
API key metadata is cached for 60 seconds (TTL). After the TTL expires, the next request will fetch fresh data from Redis.
Multiple router instances share the same Redis backend but maintain independent caches. Changes made via rpc-admin will be eventually consistent across all instances within 60 seconds.
There is no manual cache invalidation. To force immediate enforcement of key changes:
  • Restart the router (recommended for critical changes)
  • Wait up to 60 seconds for the cache to expire naturally

Build docs developers (and LLMs) love

Get started for freeTalk to us