# 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.

## Step 1 — Discover

Discovery is two hops.

### 1a. Fetch the Protected Resource Metadata

```
GET https://www.thecolorshop.ws/.well-known/oauth-protected-resource
```

Response shape:

```json
{
  "resource": "https://www.thecolorshop.ws",
  "resource_name": "The Color Shop",
  "authorization_servers": ["https://www.thecolorshop.ws/.well-known/oauth-authorization-server"],
  "scopes_supported": ["read:products", "read:orders", "write:orders", "read:account", "write:account"],
  "bearer_methods_supported": ["header"]
}
```

What each field tells you:

- `resource` — the canonical URL of the API you're trying to call.
- `resource_name` — display name for the service. Surface this to the user when asking for consent.
- `authorization_servers` — base URLs of the OAuth Authorization Server(s) for this resource. The `agent_auth` block lives on one of these (see 1b).
- `scopes_supported` — scopes the resource server understands.
- `bearer_methods_supported` — how you'll send the access_token (`"header"` = `Authorization: Bearer …`).

### 1b. Fetch the Authorization Server metadata

```
GET https://www.thecolorshop.ws/.well-known/oauth-authorization-server
```

The `agent_auth` block carries the registration surface. Read it in full.

## Step 2 — Pick a method

This service supports:

1. **service_auth** — You have the user's email. A claim ceremony is required (the user confirms the code at our site).
2. **anonymous** — No user identity needed. You get limited pre-claim scopes immediately; claim ceremony is optional to unlock full scopes.

## Step 3 — Register

### service_auth

```
POST https://www.thecolorshop.ws/agent/identity
Content-Type: application/json

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

A `user_code` and `verification_uri` are returned. Surface them to the user (see Step 4).

### anonymous

```
POST https://www.thecolorshop.ws/agent/identity
Content-Type: application/json

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

An `identity_assertion` is returned with `pre_claim_scopes`. Exchange it at the token endpoint (Step 5) or proceed to claim ceremony (Step 4) to unlock `post_claim_scopes`.

## Step 4 — Claim ceremony

Surface the `verification_uri` and `user_code` to the user. The user opens the link, signs in (or creates an account at https://www.thecolorshop.ws/signup/), and enters the 6-digit code on the page they land on.

Poll the token endpoint with the claim grant:

```
POST https://www.thecolorshop.ws/accounts/token/
Content-Type: application/x-www-form-urlencoded

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

Honor the `interval` (in seconds) between polls. On `slow_down`, add at least 5s to your interval.

## Step 5 — Exchange the assertion

```
POST https://www.thecolorshop.ws/accounts/token/
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<identity_assertion>
&resource=https://www.thecolorshop.ws
```

Extract `access_token` and go to Step 6.

## Step 6 — Use the access_token

Present the `access_token` as a bearer token:

```
GET https://www.thecolorshop.ws/api/some-resource
Authorization: Bearer <access_token>
```

Refresh: re-call Step 5 with the same `identity_assertion`. When the assertion expires or `/accounts/token/` returns `invalid_grant`, restart at Step 3.

## Errors

| Code | Endpoint | Meaning |
|---|---|---|
| `anonymous_not_enabled` | `/agent/identity` | This service doesn't accept anonymous. |
| `service_auth_not_enabled` | `/agent/identity` | service_auth disabled here. |
| `invalid_request` | `/agent/identity` | Body shape or missing claims. |
| `invalid_claim_token` | `/agent/identity/claim` | claim_token wrong or expired. |
| `claim_expired` | `/agent/identity/claim` | Registration expired. Restart at Step 3. |
| `invalid_grant` | `/accounts/token/` | Assertion expired/revoked. Restart at Step 3. |
| `authorization_pending` | `/accounts/token/` (claim) | User hasn't completed yet. Retry after interval. |
| `expired_token` | `/accounts/token/` (claim) | user_code window closed. Re-initiate claim. |
| `slow_down` | `/accounts/token/` (claim) | Polling too fast. Add 5s to interval. |
| `rate_limited` (429) | any | Back off and retry. |

## Revocation

- **Credential layer** (RFC 7009): POST `token=<access_token>&token_type_hint=access_token` to `https://www.thecolorshop.ws/accounts/revoke/` to kill one access_token.
- **Registration layer** (RFC 8935): The provider can POST a Security Event Token to `https://www.thecolorshop.ws/agent/event/notify`. The service invalidates the identity assertion and all derived access_tokens.

## API Access

- **API Catalog**: https://www.thecolorshop.ws/.well-known/api-catalog
- **MCP Server Card**: https://www.thecolorshop.ws/.well-known/mcp/server-card.json
- **Agent Skills**: https://www.thecolorshop.ws/.well-known/agent-skills/index.json

## Rate Limits

API requests are subject to rate limiting. See response headers for `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After`.

## Contact

For agent integration support: customer@thecolorshop.ws