API reference

Create an identity link

POST/v1/identity-links

Create a site link, bind an agent key, or accept a recipient grant.

Requires attribution:write. Send one of the following request variants. All signatures are unpadded base64url Ed25519 signatures. The examples show the wire shape with placeholder signatures and expiry. Generate fresh signatures for your actual IDs, origin, and expiry.

Site link (omit `kind`). Requires enrollmentId, site, agentKey, recipientKeyId, emailConsent, expiresAt, and principalProof. The authenticated enrollment and active read key must belong to the submitting workspace. Expiry is a future Unix timestamp in seconds, at most 30 days ahead and within 90 days of account authentication. Email consent requires a retained verified email and a recipient key with attribution:email. The response ID is the linkId for site-link request proofs.

Network agent (`kind: network_agent`). Requires enrollmentId, agentKey, expiresAt, principalProof, and agentProof. The enrolling workspace submits the binding. The enrolled principal and the new agent key sign separately. Use distinct keys and a future expiry within 90 days of account authentication. To rotate an active binding, include rotation: { agentId, previousKey } and sign both rotation fields. The response ID is the agentId used for recipient grants.

Network grant (`kind: network_grant`). Requires agentId, site, recipientKeyId, purpose, emailConsent, expiresAt, and principalProof. The enrolled principal signs and the recipient workspace submits with its write key. The designated recipient key must be active, have attribution:read, and belong to the submitting workspace and environment. The purpose must match ^[a-z][a-z0-9_]{0,63}$. The future expiry is at most 30 days ahead and cannot exceed the agent binding expiry. Setting emailConsent: true requires a retained verified address, an eligible recipient plan, and attribution:email on the read key. Save the response ID for revocation.

Use an exact HTTPS origin with no path or trailing slash and a recipient key record ID beginning with key_. Supply only the kty, crv, and x public Ed25519 JWK fields. The request's IDs, environment, and other signed values must match the credential and proof. See the network example and proof protocol.

Headers

Idempotency-Keystringoptional

Optional. Reuse with the same body to retry link creation.

  • HTTP 201 creates the record. A matching idempotent retry returns HTTP 200 with the same response shape. HTTP 409 covers a conflicting retry, a network binding conflict, or an exhausted active-link allowance.
Request
{
  "enrollmentId": "00000000-0000-4000-8000-000000000001",
  "site": "https://receiver-b.example",
  "agentKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
  },
  "recipientKeyId": "key_recipientb",
  "emailConsent": false,
  "expiresAt": 1800000000,
  "principalProof": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
Response
{
  "id": "00000000-0000-4000-8000-000000000010",
  "expires_at": 1800000000
}