SlipItIn/.github/skills/auth-md/references/protocol-template.md

# Protocol Template

Canonical template for generating an `auth.md` file (v2, June 2026). Replace all `{{placeholders}}` with service-specific values. Delete sections for flows the service does not support.

---

## File Structure

An auth.md is organized as a numbered walkthrough the agent follows top to bottom:

1. **Title and intro** — addressed to the agent, declares real hostnames (resource server + auth server)
2. **Step 1 — Discover** — two-hop discovery (PRM → AS metadata)
3. **Step 2 — Pick a method** — decision tree
4. **Step 3 — Register** — one subsection per supported method
5. **Step 4 — Claim ceremony** — browser-based user_code ceremony (if service_auth or anonymous claim)
6. **Step 5 — Exchange the assertion** — POST identity_assertion to /oauth2/token for access_token
7. **Step 6 — Use the access_token** — how to use and refresh
8. **Errors** — error codes table
9. **Revocation** — two-layer revocation model

---

## Complete Template

```markdown
# auth.md

You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation. Follow the steps in order; do not skip ahead.

Examples use placeholder hosts: `{{base_url}}` (the resource server hosting the API you want to call) and `{{auth_server_url}}` (the authorization server that handles registration).

## Step 1 — Discover

Discovery is two hops. The 401 response that pointed you here carries a `WWW-Authenticate` header with the PRM URL:

\```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="{{base_url}}/.well-known/oauth-protected-resource"
\```

### 1a. Fetch the Protected Resource Metadata

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

Response:

\```json
{
  "resource": "{{base_url}}/",
  "resource_name": "{{service_name}}",
  "resource_logo_uri": "{{logo_url}}",
  "authorization_servers": ["{{auth_server_url}}/"],
  "scopes_supported": [{{scopes_list}}],
  "bearer_methods_supported": ["header"]
}
\```

### 1b. Fetch the Authorization Server metadata

\```http
GET /.well-known/oauth-authorization-server
\```

Response:

\```json
{
  "resource": "{{base_url}}/",
  "authorization_servers": ["{{auth_server_url}}/"],
  "scopes_supported": [{{scopes_list}}],
  "bearer_methods_supported": ["header"],
  "issuer": "{{auth_server_url}}",
  "token_endpoint": "{{auth_server_url}}/oauth2/token",
  "revocation_endpoint": "{{auth_server_url}}/oauth2/revoke",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:workos:agent-auth:grant-type:claim"
  ],
  "agent_auth": {
    "skill": "{{auth_md_url}}",
    "identity_endpoint": "{{auth_server_url}}/agent/identity",
    "claim_endpoint": "{{auth_server_url}}/agent/identity/claim",
    "events_endpoint": "{{auth_server_url}}/agent/event/notify",
    "identity_types_supported": [{{identity_types}}],
    "identity_assertion": {
      "assertion_types_supported": [{{assertion_types}}]
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
\```

## Step 2 — Pick a method

Use this decision tree:

1. **You have a session tied to a user identity and can exchange it for an ID-JAG, audience-bound to this service** → identity_assertion + id-jag.
2. **You have only the user's email** → service_auth. Claim ceremony required.
3. **You have neither** → anonymous. Claim ceremony optional; deferred until the user wants to take ownership.

Before sending: cross-check your choice against the `agent_auth` block. If your type is not in `identity_types_supported`, pick another or stop.

## Step 3 — Register

Before sending an `identity_assertion` or `service_auth` body, surface the service's `resource_name` and `resource_logo_uri` (from Step 1a) and the scope set you'll be acting under, and confirm with the user. Skip this for `anonymous`.

### identity_assertion + id-jag

<!-- DELETE THIS SECTION IF NOT SUPPORTING ID-JAG FLOW -->

Mint the ID-JAG with:
- `aud` = the `resource` from the PRM
- `iss` = your provider's issuer URL (must be on trust list)
- `email_verified: true` OR `phone_number_verified: true`
- Fresh `jti`, near-term `exp` (~5 minutes)
- `auth_time` — epoch seconds when the user last authenticated at your provider. **Required.**

\```http
POST /agent/identity
Content-Type: application/json

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

Response — no confirmation needed (200):

\```json
{
  "registration_id": "reg_...",
  "registration_type": "identity_assertion",
  "identity_assertion": "<service-signed-jwt>",
  "assertion_expires": "{{assertion_expiry}}",
  "scopes": [{{post_registration_scopes}}]
}
\```

Keep `identity_assertion` and go to Step 5.

Response — confirmation required (401, `interaction_required`):

\```json
{
  "error": "interaction_required",
  "error_description": "...",
  "registration_id": "reg_...",
  "registration_type": "identity_assertion",
  "claim_url": "{{auth_server_url}}/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "...",
  "post_claim_scopes": [{{post_claim_scopes}}],
  "claim": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "{{auth_server_url}}/login?return_to=...",
    "interval": 5
  }
}
\```

Surface `verification_uri` + `user_code` to the user (Step 4b) and poll (Step 4c).

Response — login required (401, `login_required`):

\```json
{
  "error": "login_required",
  "error_description": "auth_time is too old; re-authenticate at the provider.",
  "max_age": 3600
}
\```

Re-authenticate the user at your provider (`prompt=login`) and mint a fresh ID-JAG.

### service_auth

<!-- DELETE THIS SECTION IF NOT SUPPORTING SERVICE_AUTH FLOW -->

\```http
POST /agent/identity
Content-Type: application/json

{
  "type": "service_auth",
  "login_hint": "user@example.com"
}
\```

Response (200):

\```json
{
  "registration_id": "reg_...",
  "registration_type": "service_auth",
  "claim_url": "{{auth_server_url}}/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "{{claim_ttl}}",
  "post_claim_scopes": [{{post_claim_scopes}}],
  "claim": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "{{auth_server_url}}/login?return_to=...",
    "interval": 5
  }
}
\```

No `identity_assertion` yet. Go to Step 4.

### anonymous

<!-- DELETE THIS SECTION IF NOT SUPPORTING ANONYMOUS FLOW -->

\```http
POST /agent/identity
Content-Type: application/json

{
  "type": "anonymous"
}
\```

Response (200):

\```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "identity_assertion": "<service-signed-jwt>",
  "assertion_expires": "{{assertion_expiry}}",
  "pre_claim_scopes": [{{pre_claim_scopes}}],
  "claim_url": "{{auth_server_url}}/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "{{claim_ttl}}",
  "post_claim_scopes": [{{post_claim_scopes}}]
}
\```

The `identity_assertion` exchanges at `/oauth2/token` for an access_token with `pre_claim_scopes` immediately (Step 5). To upgrade scopes, go to Step 4.

## Step 4 — Claim ceremony

<!-- DELETE THIS ENTIRE SECTION IF ONLY SUPPORTING identity_assertion WITHOUT interaction_required -->

The end goal: get a signed-in user to confirm a 6-digit `user_code` **you supply them**. The code travels from you → user; the user authenticates to the service and types it into a page the service owns.

### 4a. Get the ceremony materials

For **service_auth** registrations and **interaction_required** responses, you already have the `claim` block from Step 3. Skip to 4b.

For **anonymous** registrations, initiate the ceremony:

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

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

Response (200):

\```json
{
  "registration_id": "reg_...",
  "claim_attempt_id": "cla_...",
  "status": "initiated",
  "expires_at": "{{claim_attempt_ttl}}",
  "claim_attempt": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "{{auth_server_url}}/login?return_to=...",
    "interval": 5
  }
}
\```

### 4b. Hand off to the user

Surface `verification_uri` and `user_code` to the user in a single message:

> Open this link, sign in (or sign up), and enter this 6-digit code: **123456**
> {{verification_uri}}

The user will:
1. Open `verification_uri`
2. Authenticate with the service (sign in or sign up)
3. Land on the claim page, see their identity displayed, type the `user_code`, and submit

### 4c. Poll for completion

Poll the standard `token_endpoint` (from AS metadata) with the profile-specific claim grant:

\```http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim
&claim_token=<claim_token>
\```

Response while waiting:

\```json
{
  "error": "authorization_pending",
  "error_description": "..."
}
\```

Response on success:

\```json
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "{{scopes}}",
  "identity_assertion": "<service-signed-jwt-v2>",
  "assertion_expires": "{{assertion_expiry}}"
}
\```

Use `access_token` immediately; cache `identity_assertion` for refresh via Step 5.

If the `user_code` window expires:

\```json
{
  "error": "expired_token",
  "error_description": "..."
}
\```

Re-call `POST /agent/identity/claim` with the same `claim_token` and `email` to mint a fresh `user_code`. If that returns `claim_expired`, restart at Step 3.

Honor `interval` (in seconds); on `slow_down` back off.

## Step 5 — Exchange the assertion

POST the `identity_assertion` to the token endpoint with the RFC 7523 JWT-bearer grant:

\```http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<identity_assertion>
&resource={{base_url}}/
\```

Response (200):

\```json
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "{{scopes}}"
}
\```

The same `identity_assertion` can be re-used to mint additional access_tokens until it expires. If `/oauth2/token` returns `invalid_grant`, restart at Step 3.

## Step 6 — Use the access_token

Present as a bearer token:

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

**Refresh:** When the access_token expires, re-call Step 5 with the same `identity_assertion`. When the identity_assertion itself expires or `/oauth2/token` returns `invalid_grant`, restart at Step 3. There is no refresh_token — the two-step pattern replaces it.

On 401 for a previously-working access_token: try Step 5 once. If that also fails, restart at Step 1.

Full API reference: `{{api_docs_url}}`

## Errors

| Code | Where | What to do |
|------|-------|------------|
| `anonymous_not_enabled` | `/agent/identity` | Pick another method from Step 2 |
| `service_auth_not_enabled` | `/agent/identity` | Pick another method |
| `issuer_not_enabled` | `/agent/identity` | Provider not on trust list. Pick another method |
| `invalid_request` | `/agent/identity` | Fix body shape, claims, signature, jti, aud problems |
| `interaction_required` (401) | `/agent/identity` (ID-JAG) | Body carries `claim` block; surface to user (Step 4) |
| `login_required` (401) | `/agent/identity` (ID-JAG) | Re-authenticate user at provider, mint fresh ID-JAG |
| `invalid_claim_token` | `/agent/identity/claim` | Restart at Step 3 |
| `claimed_or_in_flight` | `/agent/identity/claim` | Already claimed. Re-read Step 3 response |
| `claim_expired` | `/agent/identity/claim` | Registration expired. Restart at Step 3 |
| `invalid_grant` | `/oauth2/token` | Assertion expired/revoked. Restart at Step 3 |
| `invalid_client` | `/oauth2/token` | client_id not recognized |
| `unsupported_grant_type` | `/oauth2/token` | Use one of the two supported grant types |
| `authorization_pending` | `/oauth2/token` (claim) | User hasn't completed ceremony. Honor `interval` |
| `expired_token` | `/oauth2/token` (claim) | user_code window closed. Re-initiate or restart |
| `slow_down` | `/oauth2/token` (claim) | Add ≥5s to interval and retry |
| `rate_limited` (429) | any | Back off and retry |

## Revocation

Two independent layers:

- **Credential layer (RFC 7009):** POST `token=<access_token>&token_type_hint=access_token` to `{{auth_server_url}}/oauth2/revoke`. Kills one access_token. Identity assertion intact — re-run Step 5.
- **Registration layer (RFC 8935 SET delivery):** Provider POSTs a Security Event Token to `events_endpoint`. Service invalidates identity_assertion and all derived access_tokens. Agent discovers this when `/oauth2/token` returns `invalid_grant` — restart at Step 3.

On 401 for a previously-working access_token: try Step 5 once. If `/oauth2/token` succeeds, credential-layer revocation — fresh access_token works. If `invalid_grant`, registration-layer — restart at Step 3.
```

---

## Placeholder Reference

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{base_url}}` | API base URL (resource server) | `https://api.acme.com` |
| `{{service_name}}` | Human-readable service name | `Acme Notes` |
| `{{logo_url}}` | Service logo URL | `https://acme.com/logo.png` |
| `{{auth_server_url}}` | Authorization server base URL | `https://auth.acme.com` |
| `{{auth_md_url}}` | URL where auth.md is hosted | `https://acme.com/auth.md` |
| `{{scopes_list}}` | JSON array of scope strings | `"notes.read", "notes.write"` |
| `{{identity_types}}` | Supported identity types | `"anonymous", "identity_assertion", "service_auth"` |
| `{{assertion_types}}` | Supported assertion types | `"urn:ietf:params:oauth:token-type:id-jag"` |
| `{{pre_claim_scopes}}` | Scopes before claim (anonymous) | `"notes.read"` |
| `{{post_claim_scopes}}` | Scopes after claim | `"notes.read", "notes.write"` |
| `{{post_registration_scopes}}` | Scopes after ID-JAG registration | `"notes.read", "notes.write"` |
| `{{assertion_expiry}}` | Identity assertion expiry (ISO) | `2026-05-22T13:00:00.000Z` |
| `{{claim_ttl}}` | Claim token expiration (ISO) | `2026-05-22T12:00:00.000Z` |
| `{{claim_attempt_ttl}}` | Claim attempt expiration | `2026-05-22T12:10:00.000Z` |
| `{{api_docs_url}}` | Link to full API docs | `https://docs.acme.com/` |

---

## Generation Rules

1. **Keep the file concise and high-signal** — anything the agent doesn't need to register or operate belongs in main documentation, not in auth.md
2. **Use fenced code blocks with language hints** (`http`, `json`) so agents can extract templates unambiguously
3. **Declare real hostnames in the intro** — resource server and auth server — so the agent knows which host each example targets
4. **Delete sections for unsupported flows** — don't leave empty sections or "N/A" markers
5. **The PRM is authoritative** — if anything in auth.md conflicts with the PRM, the PRM wins
6. **Token exchange is always required** — registration never returns an access_token directly; always returns an identity_assertion that must be exchanged at `/oauth2/token`