# Authentication

Every request to `https://api.closefinch.com/v1` and the MCP server at `https://api.closefinch.com/mcp` carries a bearer token: an API key,
or an OAuth access token for an app or the CLI.

```bash
curl -s https://api.closefinch.com/v1/me -H "Authorization: Bearer $RA_API_KEY"
```

## API keys

- **Who makes them:** an owner, in Settings → API keys, choosing the scopes the key needs (`crm:read`, `crm:write`,
  `agents:write` and so on).
- **What they can do:** never more than the person who made it, and a key stops working when that person leaves.
- **How long they last:** 90 days by default, up to 365. A key that never expires is an owner's explicit choice, with
  a reason, and it's recorded. The creator is reminded 14 and 3 days before a key expires.
- **Where they work from:** optionally, only from the addresses you list (an IP allowlist per key), and with a rate
  limit of its own.
- **How they're kept:** shown once when created, and stored only as a hash.

## OAuth for apps and MCP clients

Apps and assistants sign in with OAuth 2.1 and PKCE. MCP clients such as Claude, ChatGPT and Cursor register
themselves (RFC 7591) and open the consent screen; self-registered apps are marked "not verified", get capped scopes,
and can't touch API keys, secrets, approvals or the audit log. Each person can disconnect the apps they've
connected under Settings → Connected apps.

The metadata is at `https://api.closefinch.com/.well-known/oauth-protected-resource/mcp`. Details: [MCP server](https://www.closefinch.com/docs/mcp).

## The CLI

`ra login --host https://api.closefinch.com` signs in with the OAuth device flow (RFC 8628): it shows a short code, you approve it
in the browser, and there's no key to paste. Scripts and CI can use a key instead (`RA_HOST`, `RA_API_KEY`).
Details: [CLI](https://www.closefinch.com/docs/cli).

## What a token can't do

Deciding approvals happens in the web app (https://app.closefinch.com) or in Slack, never with an API key or an app token. API keys
are created, changed and rolled only in the web app, and so are workflow secrets. A credential with the `keys:write`
scope can list and revoke keys (useful in an incident), so give that scope only to what needs it. Errors for missing scopes, expired keys and blocked addresses are in [Errors](https://www.closefinch.com/docs/errors).