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-666666666666The 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.
| Answer | Meaning |
|---|---|
201 | The key is registered on this sub-key. |
200 | The same key was already registered here. Nothing changed. |
400 VALIDATION_FAILED | The JWK is not exactly {kty, crv, x} for Ed25519, or the proof does not verify. |
403 AGENT_KEY_SUBKEY_ONLY | The call used the account key. Use the agent's sub-key. |
409 AGENT_KEY_ALREADY_REGISTERED | This sub-key already holds a different key. Mint a new sub-key for it. |
409 AGENT_KEY_IN_USE | This key is registered on another sub-key. Generate a new key pair. |
429 RATE_LIMITED | More 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-6f5e4d3c2b1aSend 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):
| Header | Value |
|---|---|
X-Apier-Agent-Key-Id | The registered agent_key_id. |
X-Apier-Agent-Timestamp | The current Unix time in whole seconds, within 300 seconds of Apier's clock. |
X-Apier-Agent-Signature | Ed25519, 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.
How to record an action hash with a notary record
Record the SHA-256 hash of an action your agent took, citing your own Apier receipts, and get a receipt that verifies offline. A record proves only that API key K recorded hash H, citing Apier receipts R, at time T.
How to get every check on a Norwegian company in one call
Call GET /api/v1/company/{org}/checks to get registration status, bankruptcy and liquidation flags, VAT, roles, coded signing authority, annual accounts, requirements evidence, the LEI status and the Finanstilsynet licences, each with its own status, source and freshness, and no verdict.