# Authentication and API keys

> Authenticate with an API key or OAuth, choose what a key can reach area by area, and rotate or revoke keys without downtime.

There are two ways in. Apps that other people connect, like Claude and ChatGPT, use **OAuth**: the person signs in and approves. **API keys** are for your own code and scripts.

Either way, the credential goes in the `Authorization` header of every request:

```bash
curl https://workspace.brokerandagent.com/api/public/v1/me \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

HTTP Basic works too, the way Follow Up Boss takes its key: the API key as the username and an empty password. The scheme name isn't case-sensitive. OAuth tokens only work as `Bearer`.

## Create a key

Owners and admins make keys.

1. In Workspace, open **Settings → Integrations & API**.
2. Under **API keys**, choose **New key**.
3. Name it after what will use it, and pick when it **Expires**.
4. Owners choose whose key it is: **Mine** or **The company's**.
5. Choose what it can reach (below), then **Create key**.

The key is shown once, so copy it and store it like a password. We keep only a SHA-256 hash, which means a lost key can be replaced but never recovered.

## What a key can reach

The dialog offers three choices:

| Choice | What it allows | Right for |
|---|---|---|
| **Read everything** | Reads in every area. Any write answers `403 insufficient_scope` | Dashboards and reports |
| **Leads in only** | Adds leads and reads nothing, so it can't call `GET /me` either | Lead sources, website forms and listing sites |
| **Custom** | Each area set to Off, Read, or Read and write | Syncs and integrations |

The six areas are **Contacts** (people, lists, notes and the inbox), **Deals** (pipeline, transactions and documents), **Marketing**, **Websites**, **Automations** (starting automations) and **Webhooks**. A call outside what a key allows answers `403 insufficient_access`, with the `area` in the error. `GET /me` returns the key's `access`, area by area.

Under the areas sit five scopes, which OAuth apps ask for by name:

| Scope | What it allows |
|---|---|
| `crm.read` | Read contacts, deals, the calendar, the inbox and the rest of the book the person can see |
| `crm.write` | Add and change records. Includes `leads.write` |
| `leads.write` | Send in leads. A credential with only this scope can read nothing |
| `automations.run` | Start an automation for a contact. Separate, because an automation can message clients |
| `webhooks` | Subscribe to events. Separate, because a webhook is a standing export of the book |

> [!TIP]
> Give every lead source its own **Leads in only** key. It can add leads and read nothing, so a leaked key can't expose your book.

## Personal and company keys

- **A personal key** sees exactly what the person who made it sees. If a record is private to another agent in the app, it's private to the key too.
- **A company key** (owners only) acts as the workspace's own automation identity, so it keeps working when people come and go. It can be held to a list of addresses: turn on **Only from these addresses**, and a call from anywhere else answers `403 ip_not_allowed`.

Each person can hold up to 10 active keys, and a workspace up to 10 company keys.

## Expiry, rotation and revoking

- **You choose how long a key works:** in 90 days, in a year, or never. A **Leads in only** key left at 90 days gets no end date, since it usually sits in a form or a lead source.
- **We warn you before it stops.** The key's maker gets an email 30 days and 7 days before it expires. For a company key, the workspace's owners get it.
- **Rotate** a key from its **…** menu to get a new one with the same access and the same term. The old key keeps working for 24 hours, so you can swap the new one in, then it stops on its own. You rotate your own keys; only an owner rotates a company key.
- **Revoke** a key and it answers `401` straight away. Webhooks made with that key stop too.
- **Log**, in the same menu, lists the key's calls from the last 30 days: when, which call, and how it ended.

## OAuth tokens

Apps that connect with OAuth get short-lived tokens instead of a key:

| Token | Lasts |
|---|---|
| Authorization code | 60 seconds, and works once |
| Access token | 1 hour |
| Refresh token | 30 days, renewed each time it's used |

See [Build an app with OAuth](https://brokerandagent.com/developers/oauth) for the flow and the rules on refresh tokens.

## More than one workspace

An OAuth connection can be approved for more than one workspace. Send `X-Workspace-Id` with the workspace id to say which one answers; `GET /me/workspaces` lists them.

## Errors

| Status | Code | Meaning |
|---|---|---|
| `401` | `unauthorized` | Missing, wrong, expired or revoked credential, or the person behind it is no longer an active member |
| `401` | `workspace_suspended` | The workspace is suspended |
| `403` | `insufficient_scope` | The credential's scopes don't include this call. The error names the `scope` it needs |
| `403` | `insufficient_access` | The key or connection has this `area` turned off, or set to Read for a write |
| `403` | `forbidden` | The person behind the credential can't reach that record, or their role can't make that change |
| `403` | `workspace_not_granted` | The connection can't reach that workspace |
| `403` | `wrong_audience` | A token approved for the MCP server, used on a call outside its tools |
| `403` | `ip_not_allowed` | A company key used from an address it isn't allowed |
| `403` | `ai_apps_off` | The workspace has turned off connected AI apps |
| `403` | `awaiting_approval` | The connection is waiting for an owner or admin to approve it |

Every other error is in [Requests, errors and limits](https://brokerandagent.com/developers/api/requests#errors).

## Related

- [Build an app with OAuth](https://brokerandagent.com/developers/oauth), for apps other people connect.
- [Requests, errors and limits](https://brokerandagent.com/developers/api/requests).

---

Source: https://brokerandagent.com/developers/api/authentication
