Register an Auth Context — POST /v1/auth-contexts/register

Store an encrypted credential reference for a provider. Use the returned auth_context_id in invocations instead of passing raw tokens.

Encrypts and stores a credential for a specific provider, returning an AuthContextRecord with a masked token preview. Pass the returned auth_context_id in subsequent agent invocations instead of a raw token — the full token is never surfaced again.

Request Body

subject_did · string · required

The DID of the subject who owns this credential (e.g. "did:key:z6Mk...").

provider_id · string · required

The provider this credential is scoped to.

auth_model · object · required

Describes how the credential is presented to the provider. The mode field is required:

mode	Additional fields	Description
none	—	No authentication required.
bearer_token	—	Credential is sent as a Bearer token.
capability_token	—	Credential is a capability token.
api_key_header	header_name (required)	Credential is sent in a custom HTTP header.

token · string · required

The raw credential to encrypt and store. This value is never returned after registration.

expires_at · string (ISO 8601)

Optional expiry timestamp for this credential. The node may reject invocations that reference an expired auth context.

Response

Returns 201 Created with an AuthContextRecord.

auth_context_id · string (UUID) · required

The opaque identifier to pass as auth_context_id in invocation requests.

secret_ref · string (UUID) · required

Internal reference to the encrypted secret in the secret broker. Not needed for invocations.

subject_did · string · required

The DID of the subject who owns this auth context.

provider_id · string · required

The provider this auth context is scoped to.

auth_model · object · required

The auth model as registered.

token_preview · string · required

A masked preview of the stored token (e.g. "sk-...••••••"). The full token is never returned.

created_at · string (ISO 8601) · required

UTC timestamp when this auth context was created.

expires_at · string (ISO 8601)

Expiry timestamp for this auth context, if one was provided at registration.

Example

curl -X POST http://your-node:8042/v1/auth-contexts/register \
  -H 'content-type: application/json' \
  -d '{
    "subject_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "provider_id": "acme-labs",
    "auth_model": { "mode": "bearer_token" },
    "token": "my-secret-token"
  }'

Example response

{
  "auth_context_id": "018f5a1b-2d3e-7f80-b9c0-1a2b3c4d5e6f",
  "secret_ref": "018f5a1b-9999-7f80-dead-beef00000000",
  "subject_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
  "provider_id": "acme-labs",
  "auth_model": { "mode": "bearer_token" },
  "token_preview": "my-s••••••••••",
  "created_at": "2025-01-15T12:00:00Z"
}