Build an app with OAuth

Let people connect your app to their workspace with sign in and approve, using OAuth 2.1 with PKCE. Token lifetimes, redirect rules and what people approve.

Updated Nov 11, 2026

If other people will connect your app to their workspace, use OAuth instead of asking them to paste a key. They sign in to Broker & Agent, see what your app is asking for, and approve. This is how Claude and ChatGPT connect.

We run a standard OAuth 2.1 authorization server, so most OAuth libraries work unchanged.

Discovery https://workspace.brokerandagent.com/.well-known/oauth-authorization-server
Authorize https://workspace.brokerandagent.com/login/oauth/authorize
Token https://workspace.brokerandagent.com/api/public/oauth/token
Registration https://workspace.brokerandagent.com/api/public/oauth/register (RFC 7591)
Revocation https://workspace.brokerandagent.com/api/public/oauth/revoke (RFC 7009)
PKCE Required, S256
Tokens Access tokens are oat_… bearer tokens; refresh tokens rotate

The flow#

  1. Register your app. Read the discovery document and register a client at its registration endpoint. There’s no form to fill in.
  2. Send the person to authorize. Include your PKCE challenge, the scopes you need, and resource (below).
  3. They sign in and approve. We redirect back to your app with a code. The redirect names its issuer (iss, RFC 9207).
  4. Exchange the code for tokens at the token endpoint, with your PKCE verifier. The answer’s scope says what was actually granted.
  5. Call the API with the access token as a bearer token, exactly like a key.
  6. Refresh when the access token expires. Each refresh returns a new refresh token; use the new one next time.

Registering an app#

  • Registration is open and needs no sign-in. It’s limited to 120 a minute per IP address.
  • Apps are public clients: there’s no client secret. An app has a name and 1 to 10 redirect URIs.
  • Apps nobody has used for 30 days are deleted. Register again if yours was.
  • Client ID Metadata Documents aren’t supported yet.

Redirect URIs#

A redirect URI must match exactly. It can be:

  • https on any host;
  • http on a loopback address only (127.0.0.1, localhost), for apps on the person’s own computer;
  • your app’s own custom scheme.

Tokens and how long they last#

Token Lasts
Authorization code 60 seconds, and works once
Access token 1 hour
Refresh token 30 days, renewed each time it’s used
  • Codes work once. Using a code a second time revokes the connection.
  • Refresh tokens rotate: each one works once. If your app sends the same refresh token again within 30 seconds (a network retry, say), the second is refused but the connection stays up; use the refresh token from the first answer. An old refresh token used after that revokes the connection.
  • Revoking is supported, and it removes any webhooks your app set up.

The resource parameter#

Send resource (RFC 8707) to say what the token is for:

  • the API: https://workspace.brokerandagent.com/api/public/v1 (the default when you leave it out);
  • the MCP server: https://mcp.brokerandagent.com/mcp.

Any other value is refused with invalid_target. A token approved for the MCP server works only for the calls its tools make, and answers 403 wrong_audience anywhere else.

What the person approves#

The approval screen never grants more than your app asked for. We work out the grant on our side from the scope in your authorization request, so nothing in the browser can widen it.

Your app asks for The person is offered
No scope at all Read and write, without automations or webhooks
crm.read Read only
leads.write alone Lead capture only
crm.write, with automations.run or webhooks Read and write, with the extras it named
Only automations.run or webhooks, or nothing we know Nothing. The request is refused with invalid_scope

The approval screen shows:

  • your app’s name, the host its access goes to, and Not verified by Broker & Agent unless our team has checked your app;
  • that the app will act as the person and only see what they can see;
  • which workspaces it reaches, when they belong to more than one, with All, and any I join later;
  • Contacts, Deals, Marketing and Automations, each starting where your request put it. The person can turn any of them down to Read or Off;
  • Ask me before it sends or deletes anything, on by default (below).

If the workspace requires an admin to approve new AI apps, the person is told who will be asked, and calls answer 403 awaiting_approval until an owner or admin approves. If the workspace has turned AI apps off, people can’t connect, and every connection’s calls answer 403 ai_apps_off.

Ask before sending or deleting#

With Ask me before it sends or deletes anything on, starting an automation or removing a tour stop doesn’t run. The call answers 202 with a proposal, and the person approves it in the app. The same request again returns the same proposal. Removing your own webhook still runs as asked.

Plan for both answers: a 202 with a proposal means “waiting for your person”, not “done”.

Ask for what you need#

Ask for the smallest set of scopes that does the job. automations.run and webhooks are separate scopes on purpose: an automation can message clients, and a webhook is a standing export of the book, so people see those asks called out when they approve.

Connections people can see#

Everyone manages their own connections in Settings → Integrations & API, under Connected AI apps: Access narrows an app’s areas, Log lists its calls, the switch turns asking first on or off, and Disconnect ends it. Owners and admins also see every connection under Connected by your people, and set the workspace’s rule for AI apps: Allowed, An admin approves each one, or Off.

Disconnecting revokes the tokens and removes any webhooks your app set up, so handle a 401 by asking the person to connect again.

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