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

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](https://brokerandagent.com/developers/api/authentication#what-a-key-can-reach) 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](https://www.rfc-editor.org/rfc/rfc8707)) 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.

## Related

- [Authentication and API keys](https://brokerandagent.com/developers/api/authentication)
- [Connect an AI assistant](https://brokerandagent.com/developers/mcp)

---

Source: https://brokerandagent.com/developers/oauth
