# auth.md

You are an agent. **ClawQL** supports agentic registration for MCP and API access. Follow these steps in order.

**Resource server:** `https://docs.clawql.com/`  
**Authorization server:** `https://docs.clawql.com/` (discovery metadata; production tokens may be issued by your configured IdP)

## Step 1 — Discover

### 1a. Protected Resource Metadata

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

Returns RFC 9728 metadata: `resource`, `authorization_servers`, `scopes_supported`, and `resource_documentation`.

### 1b. Authorization Server metadata

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

Includes standard OAuth 2.0 fields plus an `agent_auth` block with registration endpoints:

- `agent_auth.skill` — this document (`https://docs.clawql.com/auth.md`)
- `agent_auth.identity_endpoint` — `POST https://docs.clawql.com/agent/identity`
- `agent_auth.claim_endpoint` — `POST https://docs.clawql.com/agent/identity/claim`
- `agent_auth.events_endpoint` — `POST https://docs.clawql.com/agent/event/notify`

## Step 2 — Pick a method

1. **identity_assertion + id-jag** — when your identity provider can mint an ID-JAG audience-bound to `https://docs.clawql.com/`.
2. **service_auth** — when you have the user's email; claim ceremony required.
3. **anonymous** — register without a user identity; optional claim later.

Check `agent_auth.identity_types_supported` in the authorization server metadata.

## Step 3 — Register

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

{
  "type": "anonymous",
  "scopes": ["mcp.tools", "api.read"]
}
```

For `identity_assertion`, POST an ID-JAG instead. For `service_auth`, include `email`.

## Step 4 — Claim (if required)

For `anonymous` or `service_auth` flows, complete the claim ceremony:

```http
POST /agent/identity/claim
```

Poll `GET /agent/identity/claim/view` until the user confirms.

## Step 5 — Exchange for access token

```http
POST /.well-known/oauth-authorization-server/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

## Step 6 — Call ClawQL

Send `Authorization: Bearer <access_token>` to the MCP Streamable HTTP endpoint or protected API routes.

- MCP server card: `https://docs.clawql.com/.well-known/mcp/server-card.json`
- Agent card (A2A): `https://docs.clawql.com/.well-known/agent-card.json`
- Commerce OpenAPI: `https://docs.clawql.com/openapi.json`
- Payments discovery: `https://docs.clawql.com/.well-known/payments.json`

## Commerce

ClawQL's **native** agentic payment rails on self-hosted deployments are **Stripe**, **x402**, and **MPP** (WORM-audited). Docs.clawql.com also publishes discovery stubs for **UCP**, **ACP**, and **AP2** (planned adapters):

- Native rails guide: [ClawQL payments](https://docs.clawql.com/payments/clawql-payments)
- x402 probe: `GET https://docs.clawql.com/api/v1` returns HTTP 402 with `PAYMENT-REQUIRED` (v2)
- MPP OpenAPI: `https://docs.clawql.com/openapi.json`
- Payments discovery: `https://docs.clawql.com/.well-known/payments.json`
- UCP profile (stub): `https://docs.clawql.com/.well-known/ucp`
- ACP discovery (stub): `https://docs.clawql.com/.well-known/acp.json`
- AP2 extension URI on the agent card (planned mandates)

Live payment settlement requires a self-hosted ClawQL deployment with `clawql-payments` configured.

## Revocation

Revoke tokens at the `revocation_endpoint` from authorization server metadata (RFC 7009).

## Related docs

- [Authentication (human guide)](https://docs.clawql.com/auth) — inbound vs outbound OAuth, EMA / ID-JAG
- [Agent setup](https://docs.clawql.com/agent-setup)
- [MCP tools](https://docs.clawql.com/tools)
- [Spec configuration](https://docs.clawql.com/spec-configuration)