API keys

An API key is a credential that one node operator issues to a tenant: a developer, a team, an agent or a machine they have an agreement with. It is sent as the X-Tenzro-Api-Key header and grants access to a set of scopes on that operator's node, within a rate budget.

API keys are per operator. Each operator issues, stores and revokes keys on their own node with their own admin token; there is no network-wide key authority. A key from one RPC provider means nothing to another.

You do not need an API key to use Tenzro. Reads are open, owner actions are authorised by your own signature, and paid routes accept per-request payment over HTTP 402. A key is for when you and a provider have agreed terms in advance: a subscription, a private model, tenant storage or a database. See RPC access.

Format

Keys look like tnz_<base64url>. The plaintext is returned once, at creation. The node stores only a SHA-256 digest, compares it in constant time and never logs it.

curl -s https://rpc.tenzro.xyz/v1/chat/completions \
  -H 'content-type: application/json' \
  -H "X-Tenzro-Api-Key: $TENZRO_API_KEY" \
  -d '{"model":"<model id>","messages":[{"role":"user","content":"Hello"}]}'

The SDKs and the CLI read the key from TENZRO_API_KEY.

Scopes

A key carries one or more scopes. A key with no scopes is invalid.

storage and database are always enforced, because the key's subject is what makes a tenant the owner of their data. The other scopes are gates an operator can choose to switch on for services they monetise or rate limit.

Publishing to the marketplaces (agents, skills, tools, workflows) needs no key and no approval from any operator.

Classes

The class decides who may revoke a key.

Tiers

The tier decides how much of a reachable surface a key gets over a sliding 60-second window.

A key over budget gets -32005 with retry_after_ms, requests_per_minute and tier in the error data.

Issue a key (operator)

Issuing, listing and revoking keys are admin methods: they need your node's X-Tenzro-Admin-Token.

tenzro admin api-key create \
  --label acme-prod \
  --subject did:tenzro:human:... \
  --scope inference --scope storage \
  --tier standard \
  --rpc http://127.0.0.1:8545

tenzro admin api-key list
tenzro admin api-key revoke --key-id <key-id>

Over JSON-RPC:

curl -s http://127.0.0.1:8545 \
  -H 'content-type: application/json' \
  -H "X-Tenzro-Admin-Token: $TENZRO_ADMIN_TOKEN" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tenzro_createApiKey",
    "params": {
      "label": "acme-prod",
      "subject": "did:tenzro:human:...",
      "scopes": ["inference", "storage"],
      "class": "subject",
      "tier": "standard"
    }
  }'

The response contains the plaintext key (shown once) and a key_id. With the TypeScript SDK:

const created = await client.apiKey.create({
  label: "acme-prod",
  subject: "did:tenzro:human:...",
  scopes: ["inference", "storage"],
  tier: "standard",
});

Self-service (key holder)

A holder of a subject key can see and revoke their own keys without asking the operator. Both calls are authorised by the key itself and return only keys with the same subject.

tenzro key list-mine
tenzro key revoke-mine --key-id <key-id>

curl -s https://rpc.tenzro.xyz \
  -H 'content-type: application/json' \
  -H "X-Tenzro-Api-Key: $TENZRO_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tenzro_listMyApiKeys","params":{}}'

Each row describes everything the node will enforce for that key: scopes, class, tier, requests_per_minute, allows_write and active. A tenant can answer "what may I do here" without asking.

What keys do not do

• They do not replace signatures. An owner action, such as a transfer, still needs a signature from the paying account; a key only admits the caller to the operator's services.
• They are not network credentials. Validator set, fees and protocol parameters change only through governance, whatever key is presented.
• They are not the admin token, and they are not service keys. A service key (X-Tenzro-Service-Key) decides whether a caller may reach a private node at all; an API key decides what an admitted caller may do.

Methods

Errors

Running a node that issues keys to customers? See Run an RPC provider.