> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="subject_did" type="string" required>
  The DID of the subject who owns this credential (e.g. `"did:key:z6Mk..."`).
</ParamField>

<ParamField body="provider_id" type="string" required>
  The provider this credential is scoped to.
</ParamField>

<ParamField body="auth_model" type="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. |
</ParamField>

<ParamField body="token" type="string" required>
  The raw credential to encrypt and store. This value is never returned after registration.
</ParamField>

<ParamField body="expires_at" type="string (ISO 8601)">
  Optional expiry timestamp for this credential. The node may reject invocations that reference an expired auth context.
</ParamField>

## Response

Returns `201 Created` with an `AuthContextRecord`.

<ResponseField name="auth_context_id" type="string (UUID)" required>
  The opaque identifier to pass as `auth_context_id` in invocation requests.
</ResponseField>

<ResponseField name="secret_ref" type="string (UUID)" required>
  Internal reference to the encrypted secret in the secret broker. Not needed for invocations.
</ResponseField>

<ResponseField name="subject_did" type="string" required>
  The DID of the subject who owns this auth context.
</ResponseField>

<ResponseField name="provider_id" type="string" required>
  The provider this auth context is scoped to.
</ResponseField>

<ResponseField name="auth_model" type="object" required>
  The auth model as registered.
</ResponseField>

<ResponseField name="token_preview" type="string" required>
  A masked preview of the stored token (e.g. `"sk-...••••••"`). The full token is never returned.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)" required>
  UTC timestamp when this auth context was created.
</ResponseField>

<ResponseField name="expires_at" type="string (ISO 8601)">
  Expiry timestamp for this auth context, if one was provided at registration.
</ResponseField>

## Example

```bash theme={null}
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

```json theme={null}
{
  "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"
}
```