Authentication and API keys
Authenticate with an API key or OAuth, choose what a key can reach area by area, and rotate or revoke
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
Either way, the credential goes in the Authorization header
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.
- In Workspace, open Settings → Integrations & API.
- Under API keys, choose New key.
- Name it after what will use it, and pick when it Expires.
- Owners choose whose key it is: Mine or The company’s.
- 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
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,
Under the areas sit five scopes, which OAuth apps ask
| 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 |
Give every lead source its own Leads in only key. It can add leads and read nothing, so a leaked key can’t
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
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
401straight away. Webhooks made with thatkey 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
| 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 for the flow and the rules
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.
Related#
- Build an app with OAuth, for apps
other people connect. - Requests, errors and limits.
Something missing or wrong? Email support@brokerandagent.com and