### Install and Run Project

Source: https://github.com/workos/auth.md/blob/main/README.md

Installs project dependencies and starts the development server. Run service and provider separately using `pnpm dev:service` or `pnpm dev:provider`.

```sh
pnpm install
pnpm dev
```

--------------------------------

### Client ID Metadata Document (CIMD) Example

Source: https://github.com/workos/auth.md/blob/main/agent-providers/README.md

An example of an OAuth Client ID Metadata Document (CIMD) that agent providers can host. This document provides metadata about the client, including JWKS URI and scopes.

```json
{
  "client_id": "https://api.agent-provider.com/agent-auth.json",
  "client_name": "Agent Provider",
  "logo_uri": "https://agent-provider.com/logo.png",
  "client_uri": "https://agent-provider.com",
  "tos_uri": "https://agent-provider.com/tos",
  "policy_uri": "https://agent-provider.com/privacy",
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://agent-provider.com/.well-known/jwks.json",
  "scope": "openid email profile"
}
```

--------------------------------

### Requesting Service Credentials (POST /agent/auth)

Source: https://github.com/workos/auth.md/blob/main/agent-providers/README.md

Example of an HTTP POST request to exchange an identity assertion for service credentials, such as an access token or API key. Includes request payload and example responses.

```http
POST /agent/auth HTTP/1.1
Host: auth.service.com
Content-Type: application/json

Payload:
{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "eyJhbGc...",
  "requested_credential_type": "<access_token | api_key>"
}

200 Response (access_token):
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["api.read", "api.write"]
}

200 Response (api_key):
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "api_key",
  "credential": "sk_live_...",
  "credential_expires": null,
  "scopes": ["api.read", "api.write"]
}

400 Response:
{ "error": "invalid_audience", "message": "..." }
```

--------------------------------

### Protected Resource Metadata (PRM) Example

Source: https://github.com/workos/auth.md/blob/main/agent-providers/README.md

This JSON object represents the Protected Resource Metadata (PRM) as defined by RFC 9728. Agents discover authorization servers through this document.

```json
{
  "resource": "https://api.service.com/",
  "resource_name": "Service",
  "resource_logo_uri": "https://service.com/logo.png",
  "authorization_servers": ["https://auth.service.com/"],
  "scopes_supported": ["api.read", "api.write"],
  "bearer_methods_supported": ["header"]
}
```

--------------------------------

### Revocation Request with Logout Token

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Example of a POST request to the revocation endpoint using a logout token to invalidate credentials.

```http
POST /agent/auth/revoke HTTP/1.1
Host: auth.service.com
Content-Type: application/logout+jwt

{
  "typ": "logout+jwt",
  "alg": "kid"
}
.
{
  "iss": "https://api.agent-provider.com",
  "sub": "<opaque user identifier>",
  "aud": "https://auth.service.com",
  "jti": "<unique identifier>",
  "iat": <epoch seconds>,
  "events": {
    "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked": {}
  }
}
```

--------------------------------

### Identity Assertion Error Response

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Example of an error response during identity assertion, indicating an invalid audience. Refer to the documentation for a full list of supported error codes.

```json
{
  "error": "invalid_audience",
  "message": "..."
}
```

--------------------------------

### POST /agent/auth/claim/complete

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Finishes the claim ceremony by collecting the OTP from the user and completing the claim process.

```APIDOC
## POST /agent/auth/claim/complete

### Description
The agent collects the OTP from the user and finishes the claim ceremony.

### Method
POST

### Endpoint
/agent/auth/claim/complete

### Parameters
#### Request Body
- **claim_token** (string) - Required - The token for the claim.
- **otp** (string) - Required - The one-time password provided by the user.

### Request Example
{
  "claim_token": "clm_abc123...",
  "otp": "123456"
}

### Response
#### Success Response (200) - Anonymous
- **registration_id** (string) - The ID of the registration.
- **status** (string) - The status of the claim, expected to be "claimed".

#### Response Example (Anonymous)
{
  "registration_id": "reg_01ABC...",
  "status": "claimed"
}

#### Success Response (200) - Verified Email
- **registration_id** (string) - The ID of the registration.
- **status** (string) - The status of the claim, expected to be "claimed".
- **credential_type** (string) - The type of credential issued (e.g., "access_token").
- **credential** (string) - The issued credential.
- **credential_expires** (string) - The ISO 8601 timestamp indicating when the credential expires.
- **scopes** (array of strings) - The scopes associated with the credential.

#### Response Example (Verified Email)
{
  "registration_id": "reg_01ABC...",
  "status": "claimed",
  "credential_type": "access_token",
  "credential": "...",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["api.read", "api.write"]
}

### Errors
- **401** `otp_invalid`: The provided OTP is invalid.
- **410** `otp_expired`: The provided OTP has expired.
- **409** `previously_claimed`: This registration has already been claimed.
- **410** `claim_expired`: The claim window has closed.
```

--------------------------------

### Anonymous Registration with OTP Claim Sequence Diagram

Source: https://github.com/workos/auth.md/blob/main/README.md

This diagram illustrates the sequence of events for anonymous agent registration and subsequent claiming using an OTP. It shows the interactions between the User, Agent, and Service.

```mermaid
sequenceDiagram
    actor User
    participant Agent
    participant Service

    Agent->>Service: POST /agent/auth<br/>{ type: anonymous, requested_credential_type: api_key }
    Service->>Service: Create agent principal, scoped API key, claim record
    Service-->>Agent: 200 OK (api_key, claim_token)

    Note over Agent: Agent operates with pre-claim scopes

    User-->>Agent: Wants to take ownership
    Agent->>Service: POST /agent/auth/claim<br/>{ claim_token, email }
    Service->>User: Send claim-view email (one-time URL)
    User->>Service: GET /agent/auth/claim/view?token=...
    Service-->>User: 6-digit OTP page
    User-->>Agent: Reads OTP back
    Agent->>Service: POST /agent/auth/claim/complete<br/>{ claim_token, otp }
    Service->>Service: Swap API key perms (pre-claim → post-claim)
    Service-->>Agent: 200 OK { status: claimed }
```

--------------------------------

### Identity Assertion (Verified Email)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Initiate an authentication flow using a verified email address to obtain an API key. This process involves creating a registration, generating claim tokens, and emailing a verification link.

```APIDOC
## POST /agent/auth/identity_assertion/verified_email

### Description
Initiates an authentication flow for an agent using a verified email address to obtain an API key. This process creates a registration, generates claim tokens, and sends a verification email to the user.

### Method
POST

### Endpoint
/agent/auth/identity_assertion/verified_email

### Parameters
#### Request Body
- **type** (string) - Required - Must be `identity_assertion`.
- **assertion_type** (string) - Required - Must be `verified_email`.
- **assertion** (string) - Required - The verified email address of the user.
- **requested_credential_type** (string) - Required - Must be `api_key`.

### Request Example
```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "api_key"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, e.g., `email-verification`.
- **claim_url** (string) - The URL to claim the credential after verification.
- **claim_token** (string) - A token used for claiming the credential.
- **claim_token_expires** (string) - The expiration time of the claim token.
- **post_claim_scopes** (array) - An array of scopes that will be available after claiming.

#### Response Example
```json
{
  "registration_id": "reg_01ABC...",
  "registration_type": "email-verification",
  "claim_url": "/agent/auth/claim",
  "claim_token": "clm_abc123...",
  "claim_token_expires": "2026-04-22T12:34:56.789Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```

**Note**: Credentials are not issued directly in this response. They are issued upon successful completion of the claim flow via `/agent/auth/claim/complete`.
```

--------------------------------

### Fetch Authorization Server Metadata

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Retrieve metadata from the authorization server, including agent authentication details like registration and claim URIs.

```http
GET <authorization_servers[0]>/.well-known/oauth-authorization-server
```

--------------------------------

### Authorization Server Metadata with Agent Auth Block

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Publish this JSON document at /.well-known/oauth-authorization-server to describe supported agent authentication flows.

```json
{
  "resource": "https://api.service.com/",
  "authorization_servers": ["https://auth.service.com/"]
  "scopes_supported": ["api.read", "api.write"],
  "bearer_methods_supported": ["header"],
  "agent_auth": {
    "skill": "https://service.com/auth.md",
    "register_uri": "https://auth.service.com/agent/auth",
    "claim_uri": "https://auth.service.com/agent/auth/claim",
    "revocation_uri": "https://auth.service.com/agent/auth/revoke",
    "identity_types_supported": ["anonymous", "identity_assertion"],
    "anonymous": {
      "credential_types_supported": ["api_key"]
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "urn:ietf:params:oauth:token-type:id-jag",
        "verified_email"
      ],
      "credential_types_supported": ["access_token", "api_key"]
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

--------------------------------

### Verified-Email Identity Assertion Flow Sequence Diagram

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Outlines the sequence for agent authentication using a verified email address, involving an OTP exchange to complete the claim.

```mermaid
sequenceDiagram
    actor User
    participant Agent
    participant Service

    Agent->>Service: POST /agent/auth<br/>{ type: identity_assertion, assertion_type: verified_email, assertion: email }
    Service->>User: Send claim-view email (one-time URL)
    Service-->>Agent: 200 OK (claim_token, no credential)
    User->>Service: GET /agent/auth/claim/view?token=...
    Service-->>User: 6-digit OTP page
    User-->>Agent: Reads OTP back
    Agent->>Service: POST /agent/auth/claim/complete<br/>{ claim_token, otp }
    Service-->>Agent: 200 OK (credential)
```

--------------------------------

### POST /agent/auth/claim/attempt/challenge

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Mints an OTP for the claim page. This endpoint is called by the user's browser, not the agent, to generate a short-lived OTP for the claim process.

```APIDOC
## POST /agent/auth/claim/attempt/challenge

### Description
Mints the OTP for the claim page. Called by the user's browser when it renders the claim page, not by the agent. The user lands on the service's claim page from the email link; the page POSTs the `claim_attempt_token` (from the URL) to this endpoint to mint a short-lived OTP and display it.
Gating OTP minting behind a POST keeps the email link safe to fetch — link-preview scanners and accidental refreshes don't burn codes. Production deployments should gate this endpoint with a HAK session (or equivalent user-binding signal) so only the legitimate user can trigger a mint.

### Method
POST

### Endpoint
/agent/auth/claim/attempt/challenge

### Parameters
#### Request Body
- **claim_attempt_token** (string) - Required - The token associated with the claim attempt.

### Request Example
{
  "claim_attempt_token": "cv_abc123..."
}

### Response
#### Success Response (200)
- **type** (string) - Indicates the response type, expected to be "otp".
- **challenge** (string) - The one-time password (OTP) generated.
- **expires_at** (string) - The ISO 8601 timestamp indicating when the OTP expires.

#### Response Example
{
  "type": "otp",
  "challenge": "123456",
  "expires_at": "2026-05-04T12:10:00.000Z"
}

### Errors
- **400** `invalid_request`: Malformed body.
- **410** `claim_superseded`: Token invalid or rotated by a newer attempt.
- **409** `claim_completed`: Registration already claimed.
- **410** `claim_expired`: Claim window has closed.
```

--------------------------------

### Mint OTP for Claim Page

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Called by the user's browser on the claim page to mint a short-lived OTP. This POST request helps protect the claim link from scanners and accidental refreshes.

```json
{ "claim_attempt_token": "cv_abc123..." }
```

--------------------------------

### Service Discovery Endpoint

Source: https://github.com/workos/auth.md/blob/main/README.md

This JSON describes the service discovery endpoint, providing details about supported authorization servers, scopes, and agent authentication methods.

```json
{
  "resource": "https://api.service.com/",
  "authorization_servers": ["https://auth.service.com/"],
  "scopes_supported": ["api.read", "api.write"],
  "bearer_methods_supported": ["header"],
  "agent_auth": {
    "skill": "https://service.com/auth.md",
    "register_uri": "https://auth.service.com/agent/auth",
    "claim_uri": "https://auth.service.com/agent/auth/claim",
    "revocation_uri": "https://auth.service.com/agent/auth/revoke",
    "identity_types_supported": ["anonymous", "identity_assertion"],
    "anonymous": {
      "credential_types_supported": ["api_key"]
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "urn:ietf:params:oauth:token-type:id-jag",
        "verified_email"
      ],
      "credential_types_supported": ["access_token", "api_key"]
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

--------------------------------

### Identity Assertion Flow Sequence Diagram

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Illustrates the sequence of interactions for agent authentication using ID-JAG identity assertion, from initial resource request to successful credential issuance.

```mermaid
sequenceDiagram
    actor User
    participant Agent
    participant Provider as Agent Provider
    participant Service

    Agent->>Service: GET /api/resource
    Service-->>Agent: 401 Unauthorized<br/>WWW-Authenticate: Bearer resource_metadata="..."

    Agent->>Service: GET /.well-known/oauth-protected-resource
    Service-->>Agent: 200 OK (PRM with authorization_servers)
    Agent->>Service: GET /.well-known/oauth-authorization-server
    Service-->>Agent: 200 OK (AS metadata with agent_auth block)

    Agent->>User: Consent to assert identity to audience?
    User-->>Agent: Consent granted

    Agent->>Provider: Request audience-specific ID-JAG
    Provider-->>Agent: 200 OK (ID-JAG)

    Agent->>Service: POST /agent/auth<br/>{ type: identity_assertion, assertion: ID-JAG }
    Service->>Provider: GET /.well-known/jwks.json
    Provider-->>Service: 200 OK (JSON Web Key Set)
    Service->>Service: Verify signature + claims, match user
    Service-->>Agent: 200 OK (credentials)
```

--------------------------------

### Complete Claim Ceremony

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

The agent collects the OTP from the user and sends it along with the claim token to complete the claim process.

```json
{ "claim_token": "clm_abc123...", "otp": "123456" }
```

--------------------------------

### anonymous

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Registers an anonymous user. This method requests an API key and provides an immediate credential along with a claim token for potential future scope upgrades.

```APIDOC
## POST /agent/auth

### Description
Registers an anonymous user and requests an API key. Provides an immediate credential and a claim token for optional scope upgrades.

### Method
POST

### Endpoint
/agent/auth

### Request Body
- **type** (string) - Required - Must be "anonymous"
- **requested_credential_type** (string) - Required - Must be "api_key"

### Request Example
```json
{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, e.g., "anonymous".
- **credential_type** (string) - The type of credential issued, e.g., "api_key".
- **credential** (string) - The issued API key.
- **credential_expires** (string) - The expiration time of the credential (null if not applicable).
- **scopes** (array) - An array of pre-claim scopes associated with the credential.
- **claim_url** (string) - The URL to initiate the claim ceremony for post-claim scopes.
- **claim_token** (string) - A token required for the claim ceremony. This is returned only once.
- **claim_token_expires** (string) - The expiration time of the claim token in ISO 8601 format.
- **post_claim_scopes** (array) - Scopes available after the claim ceremony.

#### Response Example
```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "credential_type": "api_key",
  "credential": "sk_test_...",
  "credential_expires": null,
  "scopes": ["api.read"],
  "claim_url": "https://auth.service.com/agent/auth/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-21T17:26:32.915Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```
```

--------------------------------

### Anonymous Authentication

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Obtain an API key for anonymous access. This method creates a principal and issues an API key scoped to pre-claim permissions, with a scheduled expiration.

```APIDOC
## POST /agent/auth/anonymous

### Description
Authenticates an agent anonymously and issues an API key. This process involves applying rate limits, creating a principal, and issuing an API key with pre-claim permissions.

### Method
POST

### Endpoint
/agent/auth/anonymous

### Parameters
#### Request Body
- **type** (string) - Required - Must be `anonymous`.
- **requested_credential_type** (string) - Required - Must be `api_key`.

### Request Example
```json
{ "type": "anonymous", "requested_credential_type": "api_key" }
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, always `anonymous` for this endpoint.
- **credential_type** (string) - The type of credential issued, always `api_key`.
- **credential** (string) - The issued API key.
- **credential_expires** (string) - The expiration time of the API key, or null if it does not expire.
- **scopes** (array) - An array of scopes associated with the API key.
- **claim_url** (string) - The URL to claim the credential.
- **claim_token** (string) - A token used for claiming the credential.
- **claim_token_expires** (string) - The expiration time of the claim token.
- **post_claim_scopes** (array) - An array of scopes that will be available after claiming.

#### Response Example
```json
{
  "registration_id": "reg_01ABC123DEF456GHI789JKL0MN",
  "registration_type": "anonymous",
  "credential_type": "api_key",
  "credential": "sk_test_abcdefghijklmnop123456789",
  "credential_expires": null,
  "scopes": ["api.read"],
  "claim_url": "/agent/auth/claim",
  "claim_token": "clm_abc123def456ghi789jkl012mno",
  "claim_token_expires": "2026-04-22T12:34:56.789Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```
```

--------------------------------

### 4c. Submit the OTP

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Completes the claim ceremony by submitting the One-Time Password (OTP) received from the user. This upgrades scopes for anonymous registrations or finalizes email verification.

```APIDOC
## POST /agent/auth/claim/complete

### Description
Completes the claim ceremony by submitting the user-provided OTP. This upgrades scopes for anonymous registrations or finalizes email verification.

### Method
POST

### Endpoint
/agent/auth/claim/complete

### Request Body
- **claim_token** (string) - Required - The claim token obtained from the initial registration.
- **otp** (string) - Required - The 6-digit One-Time Password provided by the user.

### Request Example
```json
{
  "claim_token": "clm_...",
  "otp": "123456"
}
```

### Response
#### Success Response (anonymous)
- **registration_id** (string) - The ID of the registration.
- **status** (string) - The status of the claim, e.g., "claimed".

#### Response Example (anonymous)
```json
{ "registration_id": "reg_...", "status": "claimed" }
```

#### Success Response (email-verification)
- **registration_id** (string) - The ID of the registration.
- **status** (string) - The status of the claim, e.g., "claimed".
- **credential_type** (string) - The type of credential issued, e.g., "access_token".
- **credential** (string) - The issued access token.
- **credential_expires** (string) - The expiration time of the credential in ISO 8601 format.
- **scopes** (array) - An array of scopes associated with the credential.

#### Response Example (email-verification)
```json
{
  "registration_id": "reg_...",
  "status": "claimed",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "...",
  "scopes": ["..."]
}
```
```

--------------------------------

### POST /agent/auth/claim

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Initiates the anonymous claim entry process. This endpoint is used when a user is claiming credentials without a prior verified email registration.

```APIDOC
## POST /agent/auth/claim

### Description
Initiates the anonymous claim entry process. This endpoint is used when a user is claiming credentials without a prior verified email registration. Verified-email registrations skip this step.

### Method
POST

### Endpoint
/agent/auth/claim

### Parameters
#### Request Body
- **claim_token** (string) - Required - The token representing the claim.
- **email** (string) - Required - The email address of the user.

### Request Example
{
  "claim_token": "clm_abc123...",
  "email": "user@example.com"
}

### Response
#### Success Response (200)
- **registration_id** (string) - The stable identifier for the registration.
- **claim_attempt_id** (string) - The identifier for the current claim attempt.
- **status** (string) - The status of the claim attempt (e.g., "initiated").
- **expires_at** (string) - The timestamp when the claim attempt expires.

#### Response Example
{
  "registration_id": "reg_01ABC...",
  "claim_attempt_id": "cla_01XYZ...",
  "status": "initiated",
  "expires_at": "2026-05-04T12:10:00.000Z"
}
```

--------------------------------

### Discover Protected Resource Metadata

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Fetch the protected resource metadata from the resource server. This provides details about the API, supported scopes, and authorization servers.

```http
GET /.well-known/oauth-protected-resource
```

--------------------------------

### OTP Minting Response

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response when minting an OTP for the claim page. Includes the OTP challenge and its expiration time.

```json
{
  "type": "otp",
  "challenge": "123456",
  "expires_at": "2026-05-04T12:10:00.000Z"
}
```

--------------------------------

### Anonymous Claim Entry Request

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Use this endpoint for anonymous claim entry. It initiates the claim process by providing a claim token and the user's email address.

```json
{
  "claim_token": "clm_abc123...",
  "email": "user@example.com"
}
```

--------------------------------

### identity_assertion + email

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Registers a user using a verified email identity assertion. This method requests an API key as the credential and initiates an email to the user for verification.

```APIDOC
## POST /agent/auth

### Description
Registers a user with a verified email identity assertion and requests an API key. An email is sent to the user for verification.

### Method
POST

### Endpoint
/agent/auth

### Request Body
- **type** (string) - Required - Must be "identity_assertion"
- **assertion_type** (string) - Required - Must be "verified_email"
- **assertion** (string) - Required - The user's verified email address
- **requested_credential_type** (string) - Required - Must be "api_key"

### Request Example
```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "api_key"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, e.g., "email-verification".
- **claim_url** (string) - The URL to initiate the claim ceremony.
- **claim_token** (string) - A token required for the claim ceremony. This is returned only once.
- **claim_token_expires** (string) - The expiration time of the claim token in ISO 8601 format.
- **post_claim_scopes** (array) - Scopes available after the claim ceremony.

#### Response Example
```json
{
  "registration_id": "reg_...",
  "registration_type": "email-verification",
  "claim_url": "https://auth.service.com/agent/auth/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-21T17:31:25.994Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```
```

--------------------------------

### Identity Assertion Response (Verified Email)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response after initiating identity assertion with a verified email. It provides claim handles but no credentials, which are issued upon OTP verification.

```json
{
  "registration_id": "reg_01ABC...",
  "registration_type": "email-verification",
  "claim_url": "/agent/auth/claim",
  "claim_token": "clm_abc123...",
  "claim_token_expires": "2026-04-22T12:34:56.789Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Anonymous Registration

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Use this snippet for anonymous registration. A credential is provided immediately, along with a claim token for an optional claim ceremony to unlock additional scopes.

```http
POST /agent/auth
Content-Type: application/json

{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}
```

```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "credential_type": "api_key",
  "credential": "sk_test_...",
  "credential_expires": null,
  "scopes": ["api.read"],
  "claim_url": "https://auth.service.com/agent/auth/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-21T17:26:32.915Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Submit OTP for Claim Ceremony Completion

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Complete the claim ceremony by submitting the user-provided OTP. For anonymous registrations, this upgrades the existing API key's scope. For email-verified registrations, a new access token is issued.

```http
POST /agent/auth/claim/complete
Content-Type: application/json

{
  "claim_token": "clm_...",
  "otp": "123456"
}
```

```json
{
  "registration_id": "reg_...",
  "status": "claimed",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "...",
  "scopes": ["..."]
}
```

--------------------------------

### POST Request to /agent/auth Endpoint

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

This is the HTTP request format for the /agent/auth endpoint, which dispatches based on the 'type' field in the payload.

```http
POST /agent/auth HTTP/1.1
Host: auth.service.com
Content-Type: application/json
```

--------------------------------

### Mint Verified Email Identity Assertion

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Use this snippet to mint a verified email identity assertion. The response provides a claim token for the subsequent claim ceremony. The service emails the user during this step.

```http
POST /agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "api_key"
}
```

```json
{
  "registration_id": "reg_...",
  "registration_type": "email-verification",
  "claim_url": "https://auth.service.com/agent/auth/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-21T17:31:25.994Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Protected Resource Metadata Response

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

The response contains information about the resource, its logo, supported authorization servers, scopes, and bearer token methods.

```json
{
  "resource": "https://api.service.com/",
  "resource_name": "Service",
  "resource_logo_uri": "https://service.com/logo.png",
  "authorization_servers": ["https://auth.service.com/"]
  "scopes_supported": ["api.read", "api.write"],
  "bearer_methods_supported": ["header"]
}
```

--------------------------------

### Anonymous Authentication Successful Response

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response for anonymous authentication, providing an API key, claim details, and scopes. Note the presence of `claim_url` and `claim_token`.

```json
{
  "registration_id": "reg_01ABC123DEF456GHI789JKL0MN",
  "registration_type": "anonymous",
  "credential_type": "api_key",
  "credential": "sk_test_abcdefghijklmnop123456789",
  "credential_expires": null,
  "scopes": ["api.read"],
  "claim_url": "/agent/auth/claim",
  "claim_token": "clm_abc123def456ghi789jkl012mno",
  "claim_token_expires": "2026-04-22T12:34:56.789Z",
  "post_claim_scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Identity Assertion Response (Access Token)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response when an access token is issued after an identity assertion. Contains registration details and the access token.

```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Presenting Bearer Token

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Use the access token or API key as a Bearer token in the Authorization header for API requests.

```http
GET /api/some-resource
Authorization: Bearer <credential>
```

--------------------------------

### Trigger Claim Email (Anonymous Only)

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Initiate the claim ceremony for anonymous registrations by triggering the claim email. This step is skipped for email-verified registrations as the email is sent in Step 3.

```http
POST /agent/auth/claim
Content-Type: application/json

{
  "claim_token": "clm_...",
  "email": "user@example.com"
}
```

```json
{
  "registration_id": "reg_...",
  "claim_attempt_id": "...",
  "status": "initiated",
  "expires_at": "..."
}
```

--------------------------------

### Mint ID-JAG Identity Assertion

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Use this snippet to mint an ID-JAG identity assertion. Ensure your provider is on the service's trust list. The response provides an access token.

```http
POST /agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<your ID-JAG JWT>",
  "requested_credential_type": "access_token"
}
```

```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["..."]
}
```

--------------------------------

### Claim Completion Response (Verified Email)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response after completing the claim ceremony for a verified email user. Includes credential details and scopes.

```json
{
  "registration_id": "reg_01ABC...",
  "status": "claimed",
  "credential_type": "access_token",
  "credential": "...",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Identity Assertion Response (API Key)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response when an API key is issued after an identity assertion. Note that `credential_expires` is null for API keys.

```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "api_key",
  "credential": "sk_live_...",
  "credential_expires": null,
  "scopes": ["api.read", "api.write"]
}
```

--------------------------------

### Claim Completion Response (Anonymous)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Successful response after completing the claim ceremony for an anonymous user. Returns the registration ID and status.

```json
{ "registration_id": "reg_01ABC...", "status": "claimed" }
```

--------------------------------

### Identity Assertion (ID-JAG)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Authenticate using an ID-JAG assertion to obtain an access token or API key. This process involves verifying the ID-JAG signature and claims against trusted providers.

```APIDOC
## POST /agent/auth/identity_assertion

### Description
Authenticates an agent using an ID-JAG assertion to obtain a requested credential type (e.g., `access_token` or `api_key`). The process involves verifying the ID-JAG's signature and claims against trusted providers.

### Method
POST

### Endpoint
/agent/auth/identity_assertion

### Parameters
#### Request Body
- **type** (string) - Required - Must be `identity_assertion`.
- **assertion_type** (string) - Required - The type of assertion, e.g., `urn:ietf:params:oauth:token-type:id-jag`.
- **assertion** (string) - Required - The ID-JAG assertion.
- **requested_credential_type** (string) - Required - The type of credential to issue, e.g., `access_token` or `api_key`.

### Request Example
```json
{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "eyJhbGc...",
  "requested_credential_type": "access_token"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, e.g., `agent-provider`.
- **credential_type** (string) - The type of credential issued.
- **credential** (string) - The issued credential (e.g., access token or API key).
- **credential_expires** (string) - The expiration time of the credential in ISO 8601 format, or null if not applicable.
- **scopes** (array) - An array of scopes associated with the credential.

#### Response Example (access_token)
```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["api.read", "api.write"]
}
```

#### Response Example (api_key)
```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "api_key",
  "credential": "sk_live_...",
  "credential_expires": null,
  "scopes": ["api.read", "api.write"]
}
```

### Error Handling
- **invalid_issuer**: The issuer of the ID-JAG is not trusted.
- **invalid_signature**: The signature of the ID-JAG is invalid.
- **expired**: The ID-JAG has expired.
- **replay_detected**: The ID-JAG has been seen before.
- **invalid_audience**: The audience claim in the ID-JAG does not match the expected audience.
- **invalid_client_id**: The client ID in the ID-JAG does not resolve to a known provider identity.
- **missing_verified_email**: The ID-JAG does not contain a verified email claim when required.
- **unsupported_credential_type**: The requested credential type is not supported.
- **insufficient_user_authentication**: The authentication context did not meet the policy requirements.
```

--------------------------------

### Identity Assertion Request (ID-JAG)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Use this JSON payload to request credentials by asserting an ID-JAG token. Ensure all required fields are present and correctly formatted.

```json
{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "eyJhbGc...",
  "requested_credential_type": "access_token"
}
```

--------------------------------

### Anonymous Claim Entry Response

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

The response indicates the initiation of a claim attempt, providing identifiers for the registration and the specific attempt, along with an expiration time.

```json
{
  "registration_id": "reg_01ABC...",
  "claim_attempt_id": "cla_01XYZ...",
  "status": "initiated",
  "expires_at": "2026-05-04T12:10:00.000Z"
}
```

--------------------------------

### HTTP 401 Unauthorized with WWW-Authenticate Header

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

A 401 response may contain a WWW-Authenticate header with the PRM URL, used for initiating the discovery process.

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.service.com/.well-known/oauth-protected-resource"
```

--------------------------------

### Identity Assertion Request (Verified Email)

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Request payload for identity assertion using a verified email. This flow initiates a verification process and does not issue credentials directly.

```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "api_key"
}
```

--------------------------------

### identity_assertion + id-jag

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Registers a user using an ID-JAG identity assertion. This method is suitable when the provider is on the service's trust list. It requests an access token as the credential.

```APIDOC
## POST /agent/auth

### Description
Registers a user with an ID-JAG identity assertion and requests an access token.

### Method
POST

### Endpoint
/agent/auth

### Request Body
- **type** (string) - Required - Must be "identity_assertion"
- **assertion_type** (string) - Required - Must be "urn:ietf:params:oauth:token-type:id-jag"
- **assertion** (string) - Required - Your ID-JAG JWT
- **requested_credential_type** (string) - Required - Must be "access_token"

### Request Example
```json
{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<your ID-JAG JWT>",
  "requested_credential_type": "access_token"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **registration_type** (string) - The type of registration, e.g., "agent-provider".
- **credential_type** (string) - The type of credential issued, e.g., "access_token".
- **credential** (string) - The issued access token.
- **credential_expires** (string) - The expiration time of the credential in ISO 8601 format.
- **scopes** (array) - An array of scopes associated with the credential.

#### Response Example
```json
{
  "registration_id": "reg_...",
  "registration_type": "agent-provider",
  "credential_type": "access_token",
  "credential": "<token>",
  "credential_expires": "2026-05-04T13:00:00.000Z",
  "scopes": ["..."]
}
```
```

--------------------------------

### POST /agent/auth/revoke

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Revokes agent credentials by accepting logout tokens.

```APIDOC
## POST /agent/auth/revoke

### Description
Accepts logout tokens to revoke agent credentials. The provider signs a logout token referencing the delegation to revoke.

### Method
POST

### Endpoint
/agent/auth/revoke

### Parameters
#### Request Body
- **Content-Type**: `application/logout+jwt`
- **Body**: A signed logout token (JWT) containing revocation information.

### Request Example
```http
POST /agent/auth/revoke HTTP/1.1
Host: auth.service.com
Content-Type: application/logout+jwt

{
  "typ": "logout+jwt",
  "alg": "HS256",
  "kid": "some-key-id"
}
.
{
  "iss": "https://api.agent-provider.com",
  "sub": "<opaque user identifier>",
  "aud": "https://auth.service.com",
  "jti": "<unique identifier>",
  "iat": <epoch seconds>,
  "events": {
    "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked": {}
  }
}
```

### Response
#### Success Response (200)
Indicates successful revocation.

#### Error Response (400)
Indicates verification failure of the logout token.
```

--------------------------------

### 4a. Trigger the claim email (anonymous only)

Source: https://github.com/workos/auth.md/blob/main/AUTH.md

Triggers the claim email for anonymous registrations. This endpoint is used to initiate the claim ceremony process after an anonymous registration.

```APIDOC
## POST /agent/auth/claim

### Description
Triggers the claim email for anonymous registrations to start the claim ceremony.

### Method
POST

### Endpoint
/agent/auth/claim

### Request Body
- **claim_token** (string) - Required - The claim token obtained from the initial registration.
- **email** (string) - Required - The user's email address to send the claim email to.

### Request Example
```json
{
  "claim_token": "clm_...",
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **registration_id** (string) - The ID of the registration.
- **claim_attempt_id** (string) - The ID of this specific claim attempt.
- **status** (string) - The status of the claim initiation, e.g., "initiated".
- **expires_at** (string) - The expiration time of the claim attempt.

#### Response Example
```json
{
  "registration_id": "reg_...",
  "claim_attempt_id": "...",
  "status": "initiated",
  "expires_at": "..."
}
```
```

--------------------------------

### Identity Assertion (ID-JAG) Header

Source: https://github.com/workos/auth.md/blob/main/agent-providers/README.md

The header for an Identity Assertion (ID-JAG) token, specifying the token type and signing algorithm.

```json
{
  "typ": "oauth-id-jag+jwt",
  "alg": "ES256", // or RS256, etc.
  "kid": "<provider key id>"
}
```

--------------------------------

### Anonymous Authentication Request

Source: https://github.com/workos/auth.md/blob/main/agent-services/README.md

Request payload for anonymous authentication, typically used to obtain an API key. Specify the desired credential type.

```json
{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}
```