# auth.md — how agents get credentials for Better Call Claude

## Audience

Autonomous agents and agent platforms that want to call the Better Call Claude
MCP server or the public people-search API on behalf of a user.

## Base URL

https://bettercallclaude.org

## Registration endpoint

POST https://bettercallclaude.org/api/public/agent-auth/register

Request body:

```json
{ "client_name": "Your agent name", "contact_email": "you@example.com" }
```

Response:

```json
{ "api_key": "bcc_live_...", "scopes": ["people-search:read", "guides:read", "impact:read"], "rate_limit": "20 requests/hour" }
```

A human can also self-serve a key at https://bettercallclaude.org/for-agents.

## Supported methods

| Method | Where | Notes |
| --- | --- | --- |
| Bearer API key | `Authorization: Bearer <api_key>` | Primary method for the REST API and MCP server. |
| Anonymous | none | Read-only MCP tools (state guides, country guides, impact totals) need no key. |
| x402 inline payment | `X-PAYMENT` header | Pay per call on metered routes without registering. See https://bettercallclaude.org/.well-known/x402.json |

## How credentials are used

Send the key on every request:

```
GET https://bettercallclaude.org/api/public/people-search?name=Jane%20Doe
Authorization: Bearer bcc_live_...
```

Keys are rate limited to 20 requests per hour per key. Keys are scoped; a
request outside its scope returns 403. Revoke or rotate keys at
https://bettercallclaude.org/for-agents.

## Related discovery documents

- https://bettercallclaude.org/.well-known/oauth-protected-resource
- https://bettercallclaude.org/.well-known/oauth-authorization-server
- https://bettercallclaude.org/.well-known/api-catalog
- https://bettercallclaude.org/openapi.json