# auth.md

You are an agent. BibiGPT supports agent registration over OAuth 2.1 (PKCE) and long-lived Bearer tokens. Follow the steps in order.

Audience: agents that want to call `https://bibigpt.co/api/mcp` (MCP, Streamable HTTP) or the REST API at `https://bibigpt.co/api/v1`.

## Step 1 — Discover

Unauthenticated calls to the MCP resource return:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://bibigpt.co/.well-known/oauth-protected-resource-mcp", scope="read"
```

1. Fetch Protected Resource Metadata:

```http
GET https://bibigpt.co/.well-known/oauth-protected-resource
GET https://bibigpt.co/.well-known/oauth-protected-resource-mcp
```

Origin-level `resource` is `https://bibigpt.co`. The MCP resource identifier is `https://bibigpt.co/api/mcp`. Use the MCP identifier as `aud` / resource when talking to `/api/mcp`.

2. Fetch Authorization Server metadata:

```http
GET https://bibigpt.co/.well-known/oauth-authorization-server
```

`issuer` is `https://bibigpt.co`. `agent_auth.skill` points back to this document. `agent_auth.register_uri` is RFC 7591 Dynamic Client Registration.

## Step 2 — Pick a method

| You have | Use |
|---|---|
| Nothing yet | **anonymous** — RFC 7591 DCR + PKCE authorization code, or a dashboard Bearer token |
| A user who can sign in in a browser | Same OAuth code flow; the user consents at `authorization_endpoint` |
| An existing API token | `Authorization: Bearer $BIBI_API_TOKEN` from https://bibigpt.co/user/integration |

BibiGPT does not currently accept ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) or verified-email claim ceremonies. Do not POST `/agent/identity` — that path does not exist. Use DCR + PKCE or Bearer.

## Step 3 — Register (anonymous / DCR)

```http
POST https://bibigpt.co/api/auth/register
Content-Type: application/json

{
  "client_name": "Your Agent",
  "redirect_uris": ["https://your-agent.example/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "read"
}
```

Response `201`:

```json
{
  "client_id": "bibigpt-dcr-…",
  "token_endpoint_auth_method": "none"
}
```

Public client, PKCE `S256` required. No `client_secret`.

## Step 4 — Exchange for an access token

1. Send the user (or a local loopback) to:

```
https://bibigpt.co/api/auth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&scope=read
```

2. POST the authorization code to `https://bibigpt.co/api/auth/token` with `grant_type=authorization_code` and the PKCE verifier.

3. Call the API with `Authorization: Bearer <access_token>`.

Dashboard tokens work the same way: https://bibigpt.co/user/integration

## Step 5 — Call the API

- MCP: `https://bibigpt.co/api/mcp` (Streamable HTTP)
- OpenAPI: `https://bibigpt.co/api/openapi.json`
- Agent landing: https://bibigpt.co/mcp

`scopes_supported`: `read` (library, summaries, content).

## Payment (HTTP 402)

Anonymous agent-skill / CLI calls that exceed free quota return **HTTP 402**. This is Alipay 智能收 (AI Pay), not a Coinbase USDC wallet.

- Response header: `Payment-Needed` (base64url JSON; Alipay `alipay.aipay.agent.payment`)
- Discovery: `GET https://bibigpt.co/api` also returns HTTP 402 with an x402 `PAYMENT-REQUIRED` envelope that names the Alipay scheme
- After paying, retry with `Payment-Proof`
- Human checkout: https://bibigpt.co/shop (Alipay / WeChat / Lemon Squeezy)

Do not treat 402 as a hard failure. See the `bibi` skill `references/billing-aipay.md` if present.

## Human docs

- Agent install: https://bibigpt.co/agent
- MCP landing: https://bibigpt.co/mcp
- Pricing: https://bibigpt.co/pricing.md
