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.

Updated Nov 11, 2026

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:

Shell
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 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.

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.