# Breakcold auth.md

You are an agent. Breakcold supports agent discovery and credentialed access to the CRM REST API and hosted MCP server. Follow these steps in order.

This document is the agent registration skill advertised from `https://www.breakcold.com/.well-known/oauth-authorization-server` as `agent_auth.skill`.

## Audience

- **Resource servers:** `https://rest.breakcold.com/api/v1` (REST) and `https://mcp.breakcold.com/mcp/v1` (MCP, Streamable HTTP).
- **Authorization server:** `https://www.breakcold.com` (discovery) issuing tokens through `https://rest.breakcold.com/oauth2/*`.
- **Human product:** `https://us.breakcold.com/signup` (trial) and `https://us.breakcold.com/login` (login).

## Step 1 — Discover

Fetch protected resource metadata, then authorization server metadata.

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

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

Read `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported` from PRM. The authorization server document includes `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `grant_types_supported`, and an `agent_auth` block with `register_uri`, identity types, credential types, `claim_uri`, and `revocation_uri`.

OIDC discovery is also published at `https://www.breakcold.com/.well-known/openid-configuration`.

## Step 2 — Choose a registration method

Breakcold supports these methods. Prefer the one your runtime already has.

### OAuth authorization code (end-user MCP clients)

Use this for Claude, ChatGPT, Cursor, and other interactive clients.

1. Register or use a public client at `https://rest.breakcold.com/oauth2/register` if the client supports OAuth dynamic client registration.
2. Send the user through `https://rest.breakcold.com/oauth2/authorize` with `response_type=code` and PKCE `S256`.
3. Exchange the code at `https://rest.breakcold.com/oauth2/token`.
4. Call MCP or REST with `Authorization: Bearer <access_token>`.

### API key (service agents)

Use this for automations, cron jobs, and headless agents.

1. Ask the user to open Breakcold → Settings → API keys → Create key.
2. Choose only the scopes you need. Supported scopes: records:read, records:write, tasks:read, tasks:write, notes:read, notes:write, inbox:read, inbox:send, crm:metadata:read, crm:metadata:write, inbox:views:read, inbox:views:write, meetings:read, webhooks:write.
3. Send `Authorization: Bearer bc_live_…` to `https://rest.breakcold.com/api/v1` or the MCP endpoint.
4. Multi-org users must also send `X-Breakcold-Organization-Id`.

Do not ask the user to paste an API key into a public chat if a secret store is available.

### Identity assertion (ID-JAG) and verified email

`agent_auth.identity_types_supported` includes `identity_assertion` (`urn:ietf:params:oauth:token-type:id-jag` and `verified_email`) and `anonymous`.

```http
POST https://www.breakcold.com/agent/identity
Content-Type: application/json

{"type":"identity_assertion","assertion":"<id-jag-or-verified-email>"}
```

```http
POST https://www.breakcold.com/agent/identity
Content-Type: application/json

{"type":"anonymous"}
```

If the response includes a claim ceremony, send the user to `claim.verification_uri` and poll as described in the authorization server metadata. Claim completion uses:

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

Credential types issued after a successful exchange are `access_token` and `api_key`. Revoke at `https://rest.breakcold.com/oauth2/token` (`revocation_uri`).

## Step 3 — Call the APIs

REST:

```http
GET https://rest.breakcold.com/api/v1/workspaces
Authorization: Bearer YOUR_TOKEN
```

MCP: `https://mcp.breakcold.com/mcp/v1`

Docs: https://docs.breakcold.com/api/authentication, https://docs.breakcold.com/api/overview, https://docs.breakcold.com/api/mcp.

## Step 4 — Handle errors

- `401 Unauthorized` — missing, expired, or revoked token. Re-run discovery; the response may include `WWW-Authenticate: Bearer resource_metadata="https://www.breakcold.com/.well-known/oauth-protected-resource"`.
- `403 Forbidden` — missing scope or workspace access. Ask the user to create a key with the needed scopes.
- `429 Too Many Requests` — wait for `Retry-After` and resume.

## Registration endpoints (machine-readable)

- `register_uri`: https://www.breakcold.com/agent/identity
- `claim_uri`: https://www.breakcold.com/agent/identity/claim
- `revocation_uri`: https://rest.breakcold.com/oauth2/token
- Supported identity types: identity_assertion, anonymous, service_auth
- Supported credentials: access_token, api_key