Redeem an enrollment token for an agent key

POST

/v1/enroll

• Production
• Local

Validates the token (not revoked/expired/exhausted) and creates a permissioned agent key bound to an agent. Idempotent on agent_handle. Also accepts a client-supplied idempotency key (Idempotency-Key header or client_id body field) to replay the original response on retry.

Parameters

Header Parameters

Idempotency-Key

string

Optional client-supplied key making a CREATE exactly-once. A retry with the same key returns the ORIGINAL response (same status + body) instead of creating a duplicate; the same key with a different request body returns 409. The body field client_id is honored as an alias when this header is absent. The key is scoped per tenant (and per agent on the agent plane), so keys never collide across callers.

Request Body ^required

object

token

required

string

Example

pk_enroll_<id>_<secret>

agent_handle

Idempotency key for the agent identity.

string

agent_name

string

client_id

Optional idempotency key (alias for the Idempotency-Key header). A retry with the same key replays the original enrollment response.

string

Responses

201

Agent key created (shown once).

object

agent_id

string

agent_key

Pk_agent_…, shown once.

string

scopes

Array<string>

org_id

The fixed org the new key is bound to (the token’s resolved org).

string

project_id

The fixed project the new key is bound to (the token’s resolved project); the agent cannot change it.

string

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

409

The supplied idempotency key was already used with a different request body (error = idempotency_conflict).

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope