# Agent Authentication & Authorization Guide (agentdiet.dev)

> WorkOS `auth.md` v1.0 & RFC 9728 / RFC 8414 / x402 v2 / IETF MPP machine-readable authentication specification for `https://agentdiet.dev`.

## Discover

Autonomous agents can discover authentication and payment metadata at:

- **OAuth 2.0 Issuer (`issuer`):** `https://agentdiet.dev`
- **OAuth 2.0 Token Endpoint (`token_endpoint`):** `https://agentdiet.dev/oauth/token`
- **Personal Agent Protocol Discovery (`poppy.json`):** `https://agentdiet.dev/.well-known/poppy.json`
- **Protected Resource Metadata (RFC 9728):** `https://agentdiet.dev/.well-known/oauth-protected-resource`
- **Authorization Server Metadata (RFC 8414 + `agent_auth`):** `https://agentdiet.dev/.well-known/oauth-authorization-server`
- **Web Bot Auth Directory (RFC 9421):** `https://agentdiet.dev/.well-known/http-message-signatures-directory`
- **Agent Identity Endpoint (`identity_endpoint`):** `https://agentdiet.dev/agent/identity`
- **Agent Claim Endpoint (`claim_endpoint`):** `https://agentdiet.dev/agent/claim`
- **Agent Events Endpoint (`events_endpoint`):** `https://agentdiet.dev/agent/events`
- **Protected Auth Challenge Probe:** `https://agentdiet.dev/agent/auth` (emits `WWW-Authenticate: Bearer resource_metadata="https://agentdiet.dev/.well-known/oauth-protected-resource"`)

## Pick a method

Choose the authentication or settlement flow matching your agent runtime:

1. **`anonymous` (Free Sandbox Preview):** Call `GET https://agentdiet.dev/v1/try/distill` or `POST https://agentdiet.dev/mcp` (`tools/list`, `resources/list`, `prompts/list`) with no credentials required.
2. **`identity_assertion` (ID-JAG / OAuth 2.0 Token Exchange):** Present an `urn:ietf:params:oauth:token-type:id-jag` assertion to `https://agentdiet.dev/agent/identity` or `https://agentdiet.dev/v1/billing/topup`.
3. **`service_auth` (Session Key / Bearer Token / x402 / MPP):** Authenticate with `Authorization: Bearer <access_token>`, `PAYMENT-SIGNATURE` (x402 v2 Base USDC to `0xEC5275D5b03bc390FcA63D902d0B2D0Db2eb5573`), or `Authorization: Payment` (IETF MPP).

## Register

Register an autonomous agent identity dynamically with zero human intervention:

```bash
curl -sS -X POST https://agentdiet.dev/agent/identity   -H "Content-Type: application/json"   -d '{"agent_name":"autonomous-worker-01","identity_type":"identity_assertion","assertion_type":"urn:ietf:params:oauth:token-type:id-jag"}'
```

## Claim

Link or claim an existing agent identity or human workspace session via `claim_endpoint`:

```bash
curl -sS -X POST https://agentdiet.dev/agent/claim   -H "Content-Type: application/json"   -d '{"agent_id":"ag_01","claim_token":"clm_demo"}'
```

## Exchange

Exchange an `identity_assertion` (`urn:ietf:params:oauth:token-type:id-jag`) or `service_auth` credential for an `access_token` at the token endpoint:

```bash
curl -sS -X POST https://agentdiet.dev/v1/billing/topup   -H "Content-Type: application/json"   -d '{"grant_type":"urn:ietf:params:oauth:grant-type:token-exchange","subject_token_type":"urn:ietf:params:oauth:token-type:id-jag","subject_token":"eyJ..."}'
```

## Use the access_token

Include the `access_token` in the `Authorization: Bearer <access_token>` header on API or MCP calls:

```bash
curl -sS https://agentdiet.dev/agent/auth   -H "Authorization: Bearer agd_live_session_token"
```

## Errors

Unauthenticated requests to `https://agentdiet.dev/agent/auth` return `HTTP 401 Unauthorized` with `WWW-Authenticate: Bearer resource_metadata="https://agentdiet.dev/.well-known/oauth-protected-resource"` and an `application/problem+json` body. Paid endpoints (`/v1/*`) without payment headers return `HTTP 402 Payment Required` with x402 v2 and IETF MPP challenges.

## Revocation

Revoke an active `access_token` or session pass at any time by calling `DELETE https://agentdiet.dev/agent/identity` or `POST https://agentdiet.dev/agent/events` with `{"event":"token.revoke"}`.