Broker API

Every endpoint a conforming identity broker serves, with request and response shapes.

Base URL of the default broker: https://id.interagentic.dev

Any host serving these endpoints is a broker. Nothing in the protocol privileges the default one.

Registration

`POST /<namespace>/register`

No authentication.

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA…\n-----END PUBLIC KEY-----",
  "algorithm": "EdDSA"
}

{ "challenge": "3f9c1e…", "expiresIn": 300 }

Code	Meaning
`200`	Challenge issued
`400`	Malformed namespace, key or algorithm
`409`	Namespace held by a different key

`POST /<namespace>/register/verify`

{ "challenge": "3f9c1e…", "signature": "MEUCIQ…" }

{
  "namespace": "acme-worker",
  "keyId": "key_V1StGXR8",
  "algorithm": "EdDSA",
  "rotatedAt": "2026-09-17T08:14:02Z"
}

Code	Meaning
`201`	Registered
`401`	Signature did not verify
`410`	Challenge expired or already used

Keys

`GET /<namespace>/jwks.json`

No authentication. Returns the namespace's public key set.

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "use": "sig",
      "kid": "key_V1StGXR8",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
    }
  ]
}

Private keys are never returned by any endpoint.

`POST /<namespace>/keys/rotate`

Authenticated with a JWT signed by the key being rotated. Stale keys are accepted here, and only here.

{ "newPublicKey": "-----BEGIN PUBLIC KEY-----…" }

{
  "keyId": "key_8Hq2Lm4P",
  "fingerprint": "SHA256:xK9c…",
  "previous": "SHA256:aB3f…",
  "rotatedAt": "2026-09-17T08:14:02Z"
}

Code	Meaning
`200`	Rotated
`409`	Already applied — idempotent replay
`423`	Namespace locked
`429`	Rotation in progress; retry after the given delay

Metadata

`GET /<namespace>/metadata.json`

Authenticated with a JWT signed by the calling service's domain key, expiring within five minutes.

{
  "namespace": "brave-fox-a3f2",
  "linked": true,
  "humanId": "h_9c3a1f7e5b2d8046",
  "permissions": ["orders:read", "orders:write"],
  "keyRotatedAt": "2026-09-17T08:14:02Z"
}

humanId is derived per calling domain and is not correlatable across services. permissions contains only grants made to the caller.

`POST /<namespace>/token` (optional)

Authenticated with a namespace JWT. Returns a broker-signed, audience-scoped token carrying the human identifier and permissions, so a service can skip the metadata round trip.

{ "audience": "api.example.com" }

Human-facing pages

Path	Purpose
`GET /<namespace>/link`	Approve linking and grant permissions
`GET /<namespace>/unlock`	Unlock a namespace after a theft lockout
`GET /approve/<id>`	Approve a charge or set a spending limit

These render HTML for a person. Agents construct the URLs and hand them over; they never follow them.

Request beta access