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
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
We run a standard OAuth 2.1 authorization server, so most OAuth
| 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#
- Register your app. Read the discovery document and register a client at its registration endpoint. There’s no form
to fill in. - Send the person to authorize. Include your PKCE challenge, the scopes you need, and
resource(below). - They sign in and approve. We redirect back to your app with a code. The redirect names its issuer (
iss, RFC 9207). - Exchange the code for tokens at the token endpoint, with your PKCE verifier. The answer’s
scopesays whatwas actually granted. - Call the API with the access token as a bearer token, exactly
like a key. - 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.
httpson any host;httpon a loopback address only (127.0.0.1,localhost), for apps on theperson’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
- the API:
https://workspace.brokerandagent.com/api/public/v1(the default when youleave 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
| 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
Plan for both answers: a 202 with a proposal means “waiting for your
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
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
Related#
Something missing or wrong? Email support@brokerandagent.com and