RPC API keys

Overview

The JSON-RPC endpoint lets clients read on-chain state from your DALP networks, and it authenticates every call with an RPC API key. These admin endpoints manage the lifecycle of those keys: issue a key, list the keys you hold, rotate one to a fresh secret, and revoke one that is no longer needed.

A key is a platform-scoped credential, separate from your REST API key. Each key carries a name, an optional expiry, and its own rate limit, so you can hand a distinct, revocable key to each client, indexer, or partner that reads from your networks.

These are administrator endpoints. The platform rejects a caller without the admin role before any key changes. To see the keys you mint here authenticate real calls, read the JSON-RPC endpoint reference.

The secret appears once

Issuing or rotating a key returns the full secret a single time, in the secret field of the response. The platform cannot show the value again. Capture it at that moment and hand it to the client that needs it.

Every secret begins with the dalp_rpc_ prefix. The response also returns a keyPrefix: the first part of the secret, safe to display, that helps an operator recognize a key in a list without exposing the full value.

Issue a key

Send a name to mint a key. Add an optional expiresAt timestamp and an optional rate limit. When you omit the rate limit, the key takes the platform default of 120 requests per 60-second window.

Size rateLimitRequests against the throughput a single client needs. The platform enforces the limit per key.

curl --request POST \
  "$PLATFORM_URL/api/v2/admin/rpc-api-keys" \
  --header "X-Api-Key: $ADMIN_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "indexer-mainnet",
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "rateLimitRequests": 240,
    "rateLimitWindowMs": 60000
  }'

The response carries the metadata plus the one-time secret:

{
  "data": {
    "id": "0c9c0b2e-7a1e-4d9a-9d2e-7c3a9f1b2c4d",
    "name": "indexer-mainnet",
    "keyPrefix": "dalp_rpc_3f9a1c2b4",
    "rateLimitRequests": 240,
    "rateLimitWindowMs": 60000,
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "revokedAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-06-24T17:00:00.000Z",
    "updatedAt": "2026-06-24T17:00:00.000Z",
    "secret": "dalp_rpc_3f9a1c2b4..."
  },
  "links": { "self": "/v2/admin/rpc-api-keys/0c9c0b2e-7a1e-4d9a-9d2e-7c3a9f1b2c4d" }
}

List keys

Read key metadata to audit what is active before issuing or revoking. The response never includes secrets. It uses the collection envelope with data, meta, and links.

curl --globoff "$PLATFORM_URL/api/v2/admin/rpc-api-keys?page[limit]=20&sort=createdAt" \
  --header "X-Api-Key: $ADMIN_API_TOKEN"

Filter by name or keyPrefix, sort by name, keyPrefix, or createdAt, and search across name and prefix with filter[q]. Each item returns the same metadata fields as an issued key, without the secret:

Use lastUsedAt to find idle keys worth retiring and revokedAt to confirm a key is already withdrawn.

Rotate a key

Rotation revokes the current key and issues a replacement in one transaction. The replacement keeps the previous key's rate limit unless you override it. Pass a new name, expiresAt, rateLimitRequests, or rateLimitWindowMs to change them; omit any field to carry the previous value forward.

curl --request POST \
  "$PLATFORM_URL/api/v2/admin/rpc-api-keys/$KEY_ID/rotate" \
  --header "X-Api-Key: $ADMIN_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "indexer-mainnet-rotated",
    "rateLimitRequests": 240,
    "rateLimitWindowMs": 60000
  }'

The response returns the new key's metadata and its one-time secret, with a fresh id. Move every client to the new secret, then confirm the old key shows a revokedAt timestamp. The old secret stops authenticating the moment rotation completes, so coordinate the cutover before you rotate a key that clients are actively using.

Revoke a key

Revoke a key to stop it immediately. A revoked key fails authentication on its next request.

curl --request DELETE \
  "$PLATFORM_URL/api/v2/admin/rpc-api-keys/$KEY_ID" \
  --header "X-Api-Key: $ADMIN_API_TOKEN"

The response returns the revoked key's metadata with revokedAt set. Revocation targets only an active key: revoking a key that is already revoked, or an unknown id, returns 404 RPC API key not found. Revoke a key as soon as it is no longer needed or may be exposed.

Error handling

These endpoints fail closed: when a lifecycle call cannot complete, the platform changes no key state and returns a typed error so an admin script can branch on the outcome. Handle each response below before you treat a key as issued, rotated, or revoked.

The 422 validation applies to issuing a key. Rotation does not accept rate-limit fields and preserves the existing limits.

A 404 on revoke is the expected result of a repeated revoke. An idempotent cleanup script can treat both the first 200 and a later 404 as "this key is now revoked." Rotation revokes the previous key and issues the replacement together. A 404 on rotate therefore means the source key was already gone and no replacement was minted. Reissue a fresh key instead of rotating in that case.

Authentication failures on the JSON-RPC endpoint itself, such as a missing, revoked, or expired key, return 401 from that endpoint rather than from these management calls. See the JSON-RPC endpoint reference for its error responses, and the Platform API error reference for the shared error envelope.

Integration notes

• Treat the secret from an issue or rotate response as write-once. Store it on receipt; the platform cannot return it again.
• Give each client its own key so you can rotate or revoke one without disrupting the others.
• Set an expiresAt on keys handed to time-bound integrations so they retire on their own.
• A 401 on the JSON-RPC endpoint means the key is missing, revoked, or expired. Refresh the client's key rather than retrying the same secret.
• The platform rejects every call on these endpoints from a caller without the admin role.

Related

• JSON-RPC endpoint for sending authenticated read calls with the keys you issue here.
• Configure RPC upstream pools for the providers and failover order behind the endpoint.
• Request headers for the headers the platform accepts on API calls.