---
title: "Bind an Ed25519 public key to one of your agent tokens"
method: POST
path: "/api/agent/keys/register"
tags: ["auth", "browser-session"]
---

# Bind an Ed25519 public key to one of your agent tokens

`POST /api/agent/keys/register`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/agent/keys/register`
- Auth: API key in cookie `__session`

Clerk-session only (NOT reachable with an agt_ bearer, deliberately — see the tag note). Binds an Ed25519 JWK to a token you own, optionally flipping `requires_signature` so later calls with that token MUST carry a valid signature. A token that is not yours is reported as unknown rather than forbidden, so this cannot be used to probe other members' tokens.

## Request body

- AgentKeyRegisterRequest
  - `sha256` string, required: The token to bind to, identified by its sha256 — never the plaintext.
  - `pubkey_jwk` Ed25519PublicJwk, required: An Ed25519 public key as a JWK. Public material only — a private key does not belong in this field.
    - `kty` 'OKP', required
    - `crv` 'Ed25519', required
    - `x` string, required: base64url public-key bytes.
  - `enforce` boolean: True also sets requires_signature. Default false, which binds the key in advisory mode.

## Response `200`

The key is bound.

- AgentKeyRegisterResponse
  - `ok` boolean, required
  - `key_id` string, required
  - `sha256` string, required
  - `prefix` string, required: The token's display prefix.
  - `requires_signature` boolean, required: Whether later calls with this token must be signed.
  - `registered_at` string, date-time, required

## Other responses

- `400`: Invalid JSON, a malformed sha256, or a JWK that is not a well-formed Ed25519 public key.
- `401`: Not signed in, or the token is not yours.
- `409`: A different key is already bound to that token — revoke it first.
- `413`: Body too large.
- `500`: KV write failed.
- `503`: Auth or KV backend unavailable.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)