# auth.md

You are an agent. **Puma Browser** (`https://www.pumabrowser.com`) publishes agent registration discovery so automated clients can authenticate to site APIs when needed.

Public marketing content, download links, blog posts, and discovery documents do **not** require a bearer token. Use registration only when calling scoped agent APIs or when you need an identity for rate-limited MCP access.

## Audience

Agents that want structured product data, download URLs, careers listings, or MCP tool access for Puma Browser.

## Step 1 — Discover

### 1a. Protected Resource Metadata

```http
GET https://www.pumabrowser.com/.well-known/oauth-protected-resource
```

- `resource` — `https://www.pumabrowser.com/`
- `authorization_servers` — `["https://www.pumabrowser.com"]`
- `scopes_supported` — `site:read`, `agent:register`
- `bearer_methods_supported` — `header`

### 1b. Authorization Server metadata

```http
GET https://www.pumabrowser.com/.well-known/oauth-authorization-server
```

Read `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `grant_types_supported`, and the `agent_auth` block (`register_uri`, identity types, claim/revocation URLs).

OpenID Connect discovery is also published at `/.well-known/openid-configuration`.

## Step 2 — Pick a method

1. **Anonymous** — register without a user identity for `site:read` access.
2. **Verified email** — send `login_hint` with the user’s email; complete the claim ceremony if prompted.
3. **Identity assertion (ID-JAG)** — if your agent provider can mint an audience-bound ID-JAG for `https://www.pumabrowser.com/`.

## Step 3 — Register

```http
POST https://www.pumabrowser.com/agent/register
Content-Type: application/json
```

Anonymous:

```json
{ "type": "anonymous", "scopes": ["site:read"] }
```

Verified email:

```json
{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "login_hint": "user@example.com",
  "scopes": ["site:read", "agent:register"]
}
```

Human fallback: email `rawr@pumabrowser.com` with subject `Agent registration` and your agent name, callback URL, and requested scopes.

## Step 4 — Claim (when required)

If registration returns a `claim_token` / `user_code`, surface the verification URI to the user and poll:

```http
POST https://www.pumabrowser.com/agent/claim
Content-Type: application/json
```

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

## Step 5 — Token exchange

```http
POST https://www.pumabrowser.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
```

Use `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` with the service-signed identity assertion, or the claim grant when completing a ceremony.

## Step 6 — Call APIs

```http
GET https://www.pumabrowser.com/api/site.json
Authorization: Bearer <access_token>
```

Unauthenticated `GET` also works for public `site:read` resources today.

## Revocation

```http
POST https://www.pumabrowser.com/oauth2/revoke
```

See `agent_auth.revocation_uri` in authorization-server metadata.