Skip to content
Apier.no
Guides

How to register an agent key and sign records and requests

Register your agent's Ed25519 public key on its sub-key, then sign its notary records and its API requests with it. The receipt of a signed notary record names the key. A signature is added evidence: the API key stays the authentication.

[Cite this as: Apier.no Docs v0.1.0 — last updated 2026-11-14]

An agent key lets one agent sign what it sends to Apier. The agent registers its Ed25519 public key on the sub-key it calls with. From then on it can sign its notary records, so the record and its receipt name the key, and it can sign its API requests.

Endpoints: POST /api/v1/account/keys/{id}/subkeys mints a sub-key under one of your account keys (account session), then POST /api/v1/agent-keys registers the agent's Ed25519 public key on the sub-key it calls with (API key).

What a signature does and does not do

A signature is added evidence, checked with the key registered on the calling sub-key. It never replaces the API key: every call still authenticates with the Authorization: Bearer key, and the signature never widens that key's scopes. A signature shows which registered key signed. It does not say which agent held the key or who the agent is, and it is never a mandate to act for a company.

An unsigned call works exactly as before. A signature that does not verify is refused; it is never treated as an unsigned call.

Step 1 — Get a sub-key for the agent

The key sits on a sub-key, never on the account key, so each agent has its own. The account owner mints one with POST /api/v1/account/keys/{id}/subkeys; its id in the answer is the sub-key id you sign in step 3. A sub-key holds one agent key for life: to use another key pair, mint a new sub-key.

Step 2 — Generate an Ed25519 key pair

Generate the key pair in the agent's own system and keep the private key there. Apier only ever sees the public key, as a JWK with exactly these three members:

{ "kty": "OKP", "crv": "Ed25519", "x": "wP3f-C62FHadz5feZnrI1IQ9IaHoYUKwOPr6COSBiMw" }

x is the 32-byte public key as unpadded base64url (43 characters). Any other member, a private d included, is refused.

Step 3 — Sign the registration message

Sign this UTF-8 text with the private key, using the sub-key's id in lowercase:

apier-agent-key-v1:register:22222222-3333-4444-8555-666666666666

The signature, as unpadded base64url (86 characters), is the proof. It shows that the agent holds the private key, and a proof made for one sub-key never registers on another.

Step 4 — Register the key

Call with the sub-key itself:

curl -X POST https://www.apier.no/api/v1/agent-keys \
  -H 'Authorization: Bearer <the agent sub-key>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <a new UUID>' \
  -d '{"jwk": {"kty": "OKP", "crv": "Ed25519", "x": "wP3f-C62FHadz5feZnrI1IQ9IaHoYUKwOPr6COSBiMw"}, "proof": "OPhNQ4F2z51fMidvsRfyOdNQrDtJJnwOtQQCrNVmokL-3BqTUvaNRcQsuzSsfXHs3B5hCMg5BWg6GC6H-g_cAQ"}'

The 201 answer carries the registered key:

{
  "success": true,
  "data": {
    "agent_key": {
      "agent_key_id": "GyeVhj_kpdICNWkrJzfG9-Jfaee8ziZVRNYFB-2nDL0",
      "alg": "Ed25519",
      "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "wP3f-C62FHadz5feZnrI1IQ9IaHoYUKwOPr6COSBiMw" },
      "registered_at": "2026-11-14T12:00:00.000Z"
    }
  }
}

agent_key_id is the RFC 7638 thumbprint of the public key, so anyone who has the public key can compute it. Registering is free and needs no scope.

Step 4 — Register the key
AnswerMeaning
201The key is registered on this sub-key.
200The same key was already registered here. Nothing changed.
400 VALIDATION_FAILEDThe JWK is not exactly {kty, crv, x} for Ed25519, or the proof does not verify.
403 AGENT_KEY_SUBKEY_ONLYThe call used the account key. Use the agent's sub-key.
409 AGENT_KEY_ALREADY_REGISTEREDThis sub-key already holds a different key. Mint a new sub-key for it.
409 AGENT_KEY_IN_USEThis key is registered on another sub-key. Generate a new key pair.
429 RATE_LIMITEDMore than 10 registrations a minute for the account.

Step 5 — Sign a notary record

Add agent_key_id and agent_signature to a notary record. The signature is Ed25519 over the action hash and the cited receipt ids, ascending and comma-joined:

apier-agent-key-v1:notary:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08:5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a

Send the two fields together, or neither. The record and its signed receipt then carry agent_key_id and agent_signature, so anyone holding the public key can check the agent's signature offline. The record's fixed claim and its record_hash do not change. A key that is not the one on the calling sub-key gets 409 AGENT_KEY_NOT_REGISTERED, and a signature that does not verify gets 400 VALIDATION_FAILED; in both cases nothing is recorded or charged.

Step 6 — Sign a request

An authenticated /api/v1 request, or an MCP call to POST /api/mcp made with an API key, may carry three headers, all three or none (an MCP call signs the path /api/mcp and its JSON-RPC body; an MCP call made with an OAuth token cannot be signed and is refused with 400 VALIDATION_FAILED when it sends them):

Step 6 — Sign a request
HeaderValue
X-Apier-Agent-Key-IdThe registered agent_key_id.
X-Apier-Agent-TimestampThe current Unix time in whole seconds, within 300 seconds of Apier's clock.
X-Apier-Agent-SignatureEd25519, as unpadded base64url, over the request message below.
apier-agent-key-v1:request:<METHOD>:<path with query>:<Unix seconds>:<SHA-256 of the raw body, lowercase hex>

For a request with no body, hash the empty string. A missing header, a stale timestamp or a signature that does not verify gets 400 VALIDATION_FAILED naming the header; a key that is not the one on the calling sub-key gets 409 AGENT_KEY_NOT_REGISTERED.

På norsk

En agent registrerer sin offentlige nøkkel (Ed25519) på undernøkkelen den kaller med, med et bevis på at den har den private nøkkelen. Deretter kan den signere notarregistreringene sine, slik at registreringen og kvitteringen navngir nøkkelen, og den kan signere forespørslene sine med tre headere. En signatur er bare et tillegg: API-nøkkelen er fortsatt autentiseringen, scopes utvides aldri, og en signatur er aldri en fullmakt til å handle for et selskap. En signatur som ikke kan verifiseres, avvises.

Building with an LLM? Read llms.txt for agent-oriented integration guidance.