Set up agent and app access
Let AI agents and other companies' apps act for one of your users, with that person's approval, through BuildBase's OAuth 2.0 server.
This page is part of Agent-ready apps: letting your own users' AI agents into the app you build with BuildBase. Your users may want an AI agent, such as Claude, ChatGPT or Cursor, or another company's app to work in your app for them: read their notes, file a report, start a job. BuildBase is an OAuth 2.0 server for every app, so the agent can ask for that access the standard way. The person signs in on your hosted sign-in page, sees a consent screen that names the agent and what it wants, and presses Allow access. The agent then acts as that person and can never do more than they can. They can take the access back at any time from your app.
Note
Want to manage BuildBase itself from your AI? That is the other track, BuildBase in your AI tools: connect Claude, ChatGPT, Cursor or another AI tool to BuildBase's own MCP server, at BuildBase in your AI tools.
Warning
This is not a way for people to sign in, and it adds no button to your sign-in page. People still sign in with the methods you already offer. This page is about what they let an agent or an app do afterwards.
Before you start
- A BuildBase plan that includes the OAuth 2.0 server, for the client the agent uses, and one that includes agent readiness, for the switches on the Agent readiness tab. Your plan's limit on connected agents applies to each new one a person allows.
- A token address on your own server (the Application token URL), reachable from the internet. BuildBase asks it for the agent's token after each approval, so your server decides what the token is.
- For agents that call tools in your app, an MCP server on your side. The SDK has one: see MCP and agents.
Step by step
There are two ways for an agent to get a client: you create one for an agent or app you know, or you let agents register themselves. Both use the consent screen.
1. Create a client for the agent
Open the Settings tab in the console
(opens the console in a new tab)- In the BuildBase console, press Users in the left-hand bar (the User management area), then Authentication under Access, and the Settings tab.
- Press Create auth client. Give it a Title, such as
Acme Assistant: it is the name people see on the consent screen. Choose the OAuth 2.0 provider (agents, other apps, and devices such as TVs, via device code) type, fill in the Application token URL (https://app.acme.example/api/agent/token) and the Application profile URL, and press Create. - Copy the client ID and the Client secret from the next dialog. It is shown once. Your token address checks every request from BuildBase with this secret. (The dialog is the same as for a device client.)
- Press Edit on the new client. Under Client kind, choose Agent (third-party). That is what makes people see the consent screen. An Application (first-party) client is your own software and signs people in without one.

- Fill in the Application revoke URL (
https://app.acme.example/api/agent/token/revoke). When a person takes access back, BuildBase tells your server there, so it can stop accepting the tokens it gave out. It is optional, but without it a token you minted keeps working until it runs out. Keep Require PKCE ticked: agents prove each sign-in with a one-time secret of their own.

- Under Redirect URLs, press Add redirect URL and paste the address the agent gave you, such as
https://assistant.acme.example/oauth/callback. People are sent back there after they allow or deny.

- Under Methods, tick how people sign in before they approve, such as Email and password, and press Update.
Give the agent its client ID, its secret if it runs on a server it controls, and your OAuth 2.0 addresses (from the client's Edit sheet, under OAuth 2.0 addresses).
2. Turn on agent readiness
Open the Agent readiness tab in the console
(opens the console in a new tab)Open the Agent readiness tab. The card at the top explains the three steps: agents discover where your users sign in, get a client, and ask for consent.

In the Agent access card:
| Setting | What it does |
|---|---|
| Agent readiness | Publishes where your users sign in, so an agent can find your OAuth 2.0 addresses by itself |
| Let agents register themselves | Agents such as Claude or ChatGPT connect to your app on their own, with no client to create for each. A person still signs in and approves. Off until you turn it on (Dynamic Client Registration) |
| Base client for self-registered agents | Every agent that registers itself is copied from this client: its token, profile and revoke URLs, its sign-in methods and its secret, so your server checks every agent with the one secret it holds |
| Allow agent self-signup | Something else: lets your own server make user accounts for bots. Leave it off unless you run bots that need accounts. See Agent accounts |
| Let agents register with a person's email | An agent that knows only someone's email address asks for access in their name, the auth.md way. Off until you turn it on |
| Agent client for registered agents | The agent client the tokens are issued to. It must be one of your clients of the Agent type, with the device code grant turned on |
Turn on Agent readiness and, if you want, Let agents register themselves with Acme Assistant as the base client, then press Save changes.

Let agents register with a person's email needs one of your clients of the Agent type with Device code on. The agent never sees that client's secret: it polls with the claim token it got when it registered. With it on, an agent posts the person's address to your registration endpoint and shows them a code. They open your sign-in page, sign in as that address, type the code and approve. Only the person whose confirmed address it is can approve; anyone else who holds the code is refused, and no account is created. Your authorization server metadata then carries an agent_auth block, which is what agent readiness scanners such as isitagentready.com look for.

Under Agent client for registered agents, pick the agent client, here Acme Assistant (turn on Device code sign-in in its Edit sheet first, or it is not offered), then press Save changes.

Further down, Discovery URLs lists the addresses agents read, each with a copy button. An MCP server built with the SDK points agents to them, so you rarely send them anywhere yourself.

Self-registered agents do not crowd the Settings tab: they are hidden from the list until you pick Self-registered by agents in its Source filter. Each one is read-only and follows its base client.
Agents register again whenever they are reinstalled, so unused registrations are removed for you and never fill your limit of self-registered agents. A registration counts as unused when it was made more than an hour ago and nothing still holds a grant to it: no sign-in under way, no refresh token that has not expired, no live session, and no consent from a person who still has an account that was given within your agent refresh token idle lifetime (30 days unless you changed it). The oldest unused ones go first, once a day and again whenever an agent would be refused at the limit. Each removal is in your auth log as client_deleted, with the agent's client ID and name, and your Application revoke URL hears client_deleted for anyone who had approved it.

Agents named by a metadata document
Some agents, Claude among them, name themselves by the https address of a document they publish (a Client ID Metadata Document) instead of a client you create or one they register. Turn on Let agents identify themselves by a metadata document to let them connect. Such an agent holds no secret.

- Base client for agents identified by a metadata document: these agents use its token, profile and revoke URLs, and its secret signs their requests to your app. Left empty, it is the base client for self-registered agents.
- Vetted document hosts: the hosts whose agents your team has checked, such as
claude.ai, separated by commas. The consent screen warns that an agent from any other host is unverified.

- Most agents kept: how many of these agents your app keeps. Leave it empty for the default cap.

Then press Save changes. A document must name its own address exactly, and it is read only over https from a public address, without following redirects, and again at most once an hour. In the Settings tab, pick Metadata document in the Source filter to list these agents: each one's Type reads "Agent, identified by" its host. Like a self-registered agent, each one is read-only and follows its base client.

3. Your token address
After each approval, BuildBase asks your Application token URL for the token the agent will use, signed with the client's secret. The SDK has the whole handler:
// app/api/agent/token/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { handleAppTokenRequest, mintAgentToken } from '@buildbase/sdk';
export async function POST(request: NextRequest) {
const { status, body } = await handleAppTokenRequest({
authorization: request.headers.get('authorization'),
clientSecret: process.env.BUILDBASE_AGENT_CLIENT_SECRET!,
mintToken: (claims) =>
mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
});
return NextResponse.json(body, { status });
}The revoke address has a matching handleAppRevokeRequest({ authorization, clientSecret, onRevoke }). MCP and agents covers the MCP server and tools that use the token.
Scopes
A scope is a name for one kind of access, such as notes:read. BuildBase passes the scope names an agent asks for through to your token address, and your app decides what each one allows. The standard ones are said in words on the consent screen, in the person's language:
| Scope | The consent screen says |
|---|---|
openid | Confirm who you are |
profile | See your name and profile |
email | See your email address |
offline_access | Stay connected when you are not using it |
Name your own scopes in your MCP server's scope catalog, so agents can find them, and check them in each tool with requiredScopes.
Describe your own scopes
Your own scopes mean what your app says they mean, so tell people in your words. Describe them once for your organization, and every agent that asks for them, the ones you create and the ones that register themselves, is shown your words on the consent screen.
Open the Agent readiness tab in the console
(opens the console in a new tab)- In the BuildBase console, press Users in the left-hand bar, then Authentication under Access, and the Agent readiness tab.
- In the Scope descriptions card, press Add a scope for each one. Type the Scope exactly as agents ask for it (
designs:read) and a short Description of what allowing it lets the agent do (See your designs and their comments). - Tick Sensitive for a scope that deletes, sends, spends money, changes who has access or reads other people's data. The consent screen marks it with a warning and the word Sensitive.
- Press Save scope descriptions. The next consent screen uses them; nothing needs a redeploy.

What the consent screen shows for each scope an agent asks for:
| The scope | The consent screen shows |
|---|---|
A standard one (openid) | The words in the table above, in the person's language |
| One you described | Your description, with the scope name in small text under it |
| One you described as sensitive | The same, with a warning and the word Sensitive |
| One you did not describe | The name as written, such as reports:export |
Your descriptions are shown as you typed them, in every language. Keep them short (up to 200 characters) and say what the agent can do, not how your API works. Each change is in your auth log as agent_readiness_updated, with the list before and after.
The same list can be set with the API, for example from a setup script. The list you send replaces the stored one, and an empty list clears it:
curl -X PATCH "https://api.console.buildbase.app/api/organizations/settings/agent-readiness" \
-H "Authorization: Bearer $BUILDBASE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"scopeDescriptions":[{"name":"designs:read","description":"See your designs and their comments"},{"name":"designs:delete","description":"Delete your designs, which cannot be undone","sensitive":true}]}'Up to 50 scopes. Each name has no spaces and is listed once, and each description is 1 to 200 characters. A list that breaks one of these is refused with 400 and the stored list is kept. Saving descriptions switches nothing on, so it works on any plan.
The consent check your hosted page reads (GET /api/v1/auth/consent) answers the described scopes an agent asked for as scopeDetails, each with its name, description and sensitive, beside the plain scope list.
What people see
The agent opens your hosted sign-in page in the person's browser. They sign in as usual, then see the consent screen, named after the agent. It lists the whole grant in plain words: that the agent acts as them, which of their details the app sees, how long it stays connected, each scope it asked for and where they go back to. Then Allow access and Deny.
How the first line reads depends on what the agent asked for. When it asks for at least one of your own scopes, the screen says it will act as you, limited to the permissions below and to what your role allows. When it asks only for the standard scopes, or none, which narrow nothing it can do, it says it will act as you in this app, with the same access your account has. Your own scopes are listed in your words where you described them, with a sensitive one marked, and by name where you did not.

Allow access sends them back to the agent's redirect URL with a one-time code, which the agent exchanges for its tokens. Deny sends them back with error=access_denied, and nothing is recorded.
A self-registered agent's consent screen shows the name the agent gave itself:

On a phone:

People are asked once for each scope an agent wants. When the same agent comes back for the same scopes, the consent screen is not shown again. When it asks for more, it is shown again. To be asked about everything again, the person disconnects the agent first. The consent screen follows the person's language, in any of the 8 languages the sign-in page speaks.
Check it yourself
The sign-in page preview has no consent screen. To see the real one, have the agent connect, or open an authorization address in a browser. It needs a PKCE pair:
VERIFIER=$(openssl rand -hex 32)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
echo "https://api.console.buildbase.app/api/v1/auth/oauth2/authorize?org=$BUILDBASE_ORG_ID&client_id=$AGENT_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Fassistant.acme.example%2Foauth%2Fcallback&scope=openid%20profile%20notes%3Aread&state=check&code_challenge=$CHALLENGE&code_challenge_method=S256"In your app (SDK)
People see and take back the access they gave on the Connected agents screen of your app's settings dialog. Each agent shows the access it was given and when, with Disconnect.

Disconnect asks first, naming the agent, and Cancel leaves it connected.

Once confirmed, it takes effect at once: the agent's grant and every token it holds for that person are deleted, its refresh token stops working, and BuildBase calls your Application revoke URL so your server can stop accepting the tokens it minted.

Open it from your own button, or put the screen anywhere with ConnectedAgents:
// components/agent-access.tsx
import { ConnectedAgents, useSaaSAuth } from '@buildbase/sdk/react';
export function ManageAgentsButton() {
const { openWorkspaceSettings } = useSaaSAuth();
return (
<button onClick={() => openWorkspaceSettings('connected-agents')}>
Connected agents
</button>
);
}
export function AgentAccessPage() {
return <ConnectedAgents />;
}useConnectedAgents() gives agents, loading, error and revoke(clientId) for a screen of your own. Pass mcp={{ url: 'https://app.acme.example/mcp', name: 'Acme' }} to SaaSOSProvider to add a Connect an agent guide to the screen. To hide the screen, pass ui={{ settings: { sections: { 'connected-agents': false } } }}.
Check it works
- An authorization request for your agent client shows the consent screen after sign-in, named after the client.
- Allow access returns a code to the redirect URL, and the token exchange answers with an
access_tokenyour server minted. - Each of your own scopes the agent asks for shows your description, and each sensitive one is marked Sensitive.
- The person's Connected agents screen lists the agent.
- After Disconnect, the agent's refresh token is refused and your revoke address was called.
Things to watch out for
- People are asked again only for new access. An agent that comes back for the same scopes gets them without the consent screen. One that asks for more shows it again. To be asked about everything again, the person disconnects the agent first.
- Describe every scope your agents ask for. A scope you did not describe is shown by its bare name, which most people cannot judge. Mark the ones that delete, send, spend or share other people's data as sensitive.
- A self-registered agent chooses its own name. Nothing checks it, so anyone can register an agent named after a well-known one. Leave Let agents register themselves off unless any agent may ask your users for access.
- An agent's refresh token works once. Each refresh gives a new one. Using an old one again, for example from two copies of the agent at once, ends every token in that chain, and the person connects the agent again. An agent's refresh token also expires after 30 days unused. You can change that, and give agents a maximum from when the person connected them, under Connected apps and agents on the Security tab, beside the session lifetime.
- If your token address fails during a refresh, the agent has to reconnect. BuildBase spends the refresh token before it asks your server for the new access token.
- Your token address has 10 seconds and gets no redirects. BuildBase does not follow a redirect, so an address that redirects, such as
http://tohttps://, fails with503 temporarily_unavailable. - Without a revoke URL, disconnecting does not stop tokens you minted. They keep working until they expire.
- An agent's token works in one environment only. It is bound to the environment the person connected the agent in: production, or a development or staging environment. A request that names another environment in its
x-org-idheader (<orgId>-<key>for an environment, the org id alone for production) is refused with401 AGENT_TENANT_MISMATCH, so a Staging token used at an MCP server set up for production, or the other way round, stops there. The person connects the agent again from the right environment. A request that names no environment is not checked, and tokens issued before this check carry no environment and keep working until they expire.
If something goes wrong
| What you see | Why | What to do |
|---|---|---|
| No consent screen; the agent gets a code straight away | The client is Application (first-party), or the person already allowed this agent everything it asks for | Choose Agent (third-party). To ask again, the person disconnects the agent |
error=invalid_request, "code_challenge is required (PKCE)", at the redirect URL | Require PKCE is on and the request has no code_challenge | Send a PKCE pair, as every agent should |
| "Connecting new agents is not available right now." | Your plan's limit on connected agents is reached | Raise the plan, or have people disconnect agents they no longer use |
503 temporarily_unavailable, "The application server failed to issue a token. Try again later." | Your Application token URL did not answer with a token | Check the route is reachable and checks with this client's secret |
400 invalid_grant, "Invalid refresh token" | The person disconnected the agent | The agent asks the person to connect again |
| The agent cannot register itself | Let agents register themselves is off, or no base client is picked | Turn it on and pick a base client on the Agent readiness tab |
| A scope shows its bare name instead of your words | It is not in your scope descriptions, or its name there differs (they are case-sensitive) | Add it, spelled as agents ask for it, under Scope descriptions |
401 AGENT_TENANT_MISMATCH | The agent's token was issued in another environment than the one the request names | Connect the agent again from the environment your MCP server is set up for |
Next steps
- MCP and agents - the MCP server, tools, scopes and the token in your app.
- Device code sign-in - the same OAuth 2.0 server, for devices without a browser.
- Authentication overview - every part of the OAuth 2.0 server.
- Set up sign-in, step by step - every sign-in guide, and the order to set them up in.