# auth.md

You are an agent. This document tells you how to register and authenticate with **XiaoFlow** — the keyword intelligence, Google Ads automation, and Model Context Protocol (MCP) platform.

This is the **user claimed** flow: provision credentials anonymously, perform operations immediately, and claim or bind to a user account when available.

Endpoints live at `https://www.xiaoflow.com`.

## Step 1 — Provision the environment / Dynamic Client Registration

```http
POST /api/v1/mcp/oauth/register HTTP/1.1
Host: www.xiaoflow.com
Content-Type: application/json

{
  "client_name": "XiaoFlow Agent Client",
  "redirect_uris": ["http://localhost:8080/callback", "https://mcp.xiaoflow.com/callback"]
}
```

Response (201):

```json
{
  "client_id": "xiaoflow_mcp_01ABC123...",
  "apiKey": "xf_agent_live_credential...",
  "claimToken": "xf_claim_01ABC123...",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}
```

What each field is:
- `client_id` — unique client identifier for OAuth and MCP handshakes.
- `apiKey` — temporary bearer credential. Use it immediately in [Step 2](#step-2--use-the-credential).
- `claimToken` — handle for the optional claim ceremony in [Step 3](#step-3--claim-ceremony-optional).

## Step 2 — Use the credential

```http
GET /api/v1/user/search-ads HTTP/1.1
Host: www.xiaoflow.com
Authorization: Bearer <apiKey>
```

Or connect via Model Context Protocol (SSE / HTTP):

```http
GET /mcp HTTP/1.1
Host: mcp.xiaoflow.com
Authorization: Bearer <apiKey>
```

## Step 3 — Claim ceremony (optional)

Claim links the agent's credentials to the user's permanent XiaoFlow account.

```http
GET /mcp/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code&scope=mcp HTTP/1.1
Host: www.xiaoflow.com
```

Exchange authorization code for permanent access token:

```http
POST /api/v1/mcp/oauth/token HTTP/1.1
Host: www.xiaoflow.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<client_id>",
  "redirect_uri": "<redirect_uri>"
}
```
