Admin API

Authentication & CORS

admin.auth accepts the same strategy schema as project-level auth (secret, network, jwt, siwe). At least one strategy must be defined or the endpoint is closed. admin.cors is a separate CORS config — independent from project-level CORS. When omitted, eRPC defaults to allowedOrigins: ["*"] (permissive, safe because admin.auth is required) with the standard methods/headers. Restrict allowedOrigins explicitly when building a production admin UI.

erpc_taxonomy

Params: none.

Returns: an object with projects[]. Each project has id and networks[]. Each network has id (e.g. evm:1) and upstreams[]. Each upstream has id.

{
  "jsonrpc": "2.0",
  "result": {
    "projects": [
      {
        "id": "frontend",
        "networks": [
          {
            "id": "evm:1",
            "upstreams": [
              { "id": "blastapi-test" },
              { "id": "my-alchemy" }
            ]
          }
        ]
      }
    ]
  }
}

Use this for system discovery (e.g. an admin UI populating dropdowns).

erpc_config

Params: none.

Returns: the full resolved eRPC config as it exists in memory. Sensitive fields (secret.value, redis.password, endpoint URLs containing API keys, aws.secretAccessKey) are redacted to #redacted=<short-hash>. The short hash lets you tell two configs apart without leaking the secrets.

Useful for verifying that ${VAR} env-var interpolation resolved correctly and for runtime debugging.

erpc_project

Params: [<projectId>] — a single project ID string.

Returns: the project's resolved config (redacted) plus live runtime state — upstream scoring, error rates, block-head lag, current primary upstream, recent selection decisions. Use to debug routing problems.

curl -X POST 'http://localhost:4000/admin?secret=YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"erpc_project","params":["main"]}'

erpc_addApiKey

Inserts a new API key into a database-backed auth connector. The connector is identified by (projectId, connectorId) — connectorId matches the ID of an auth strategy's connector.

Params: [{ projectId, connectorId, apiKey, userId, rateLimitBudget?, enabled? }]

curl -X POST 'http://localhost:4000/admin?secret=YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "erpc_addApiKey",
    "params": [{
      "projectId": "main",
      "connectorId": "auth-db",
      "apiKey": "ak_live_pXq7...",
      "userId": "user-42",
      "rateLimitBudget": "tier-pro"
    }]
  }'

Returns: { success: true, apiKey, userId }.

erpc_listApiKeys

Paginated list of API keys for a connector. Reads from the main index (one row per key).

Params: [{ projectId, connectorId, limit?, paginationToken? }]

Returns: { apiKeys: ApiKey[], nextToken: string, hasMore: bool, totalReturned: number }

Each ApiKey object:

{
  "key": "ak_live_pXq7...",
  "userId": "user-42",
  "enabled": true,
  "rateLimitBudget": "tier-pro",
  "createdAt": "2026-05-15T...",
  "updatedAt": "2026-05-15T..."
}

Iterate by feeding nextToken back as paginationToken until hasMore: false.

erpc_updateApiKey

Partial update of an existing API key. Reads the current value, applies updates (a map merged into the stored JSON), writes back.

Params: [{ projectId, connectorId, apiKey, updates }]

curl -X POST 'http://localhost:4000/admin?secret=YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "erpc_updateApiKey",
    "params": [{
      "projectId": "main",
      "connectorId": "auth-db",
      "apiKey": "ak_live_pXq7...",
      "updates": {
        "enabled": false,
        "rateLimitBudget": "tier-suspended"
      }
    }]
  }'

Common updates:

• Disable a key: updates: { enabled: false }
• Change the user's tier: updates: { rateLimitBudget: "tier-pro" }
• Remove rate-limit binding: updates: { rateLimitBudget: null } (deletes the field)

Returns: { success: true, apiKey, updated } where updated echoes the map you sent.

erpc_deleteApiKey

Permanently removes an API key and its reverse index entries.

Params: [{ projectId, connectorId, apiKey }]

curl -X POST 'http://localhost:4000/admin?secret=YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "erpc_deleteApiKey",
    "params": [{
      "projectId": "main",
      "connectorId": "auth-db",
      "apiKey": "ak_live_pXq7..."
    }]
  }'

Returns: { success: true, apiKey, userId }.

Error semantics

Programmatic key rotation

A typical rotation workflow:

# 1. Add a new key for the user
erpc_addApiKey {projectId, connectorId, apiKey: NEW, userId, rateLimitBudget}
 
# 2. Switch your client to NEW
 
# 3. Wait for traffic to drain off the old key (monitor erpc_auth_secret_requests_total{secret_id=OLD})
 
# 4. Delete the old key
erpc_deleteApiKey {projectId, connectorId, apiKey: OLD}

Or simply erpc_updateApiKey with updates: { enabled: false } to soft-disable while keeping audit trail.

Common pitfalls

• Method names are case-sensitive — erpc_addapikey won't match erpc_addApiKey.
• updates: { field: null } deletes the field, it doesn't set null. To set null, use updates: { field: "null" } if your field permits the string "null" (rare).
• No batch insert — erpc_addApiKey accepts one key per call. Issue them in a loop client-side, ideally with a small concurrency limit so a slow connector doesn't block.
• erpc_config is read-only. There's no admin method to mutate config at runtime — restart the process to reload.
• Admin endpoint not blocked from public access by default — bind it via firewall or network strategy if the eRPC instance is internet-facing. The auth strategy gates access but won't stop unauthenticated requests from reaching the parser.