Skip to content
BuildBase

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)
  1. In the BuildBase console, press Users in the left-hand bar (the User management area), then Authentication under Access, and the Settings tab.
  2. 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.
  3. 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.)
  4. 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.

Client kind in the Edit auth setting sheet for Acme Assistant: Agent (third-party) chosen and ringed, for AI agents and external integrations that need the person to approve on a consent screen

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

The OAuth 2.0 settings of Acme Assistant: Application token URL and Application profile URL on app.acme.example, the Application revoke URL box ringed with https://app.acme.example/api/agent/token/revoke, Require PKCE ticked and ringed, and Device code sign-in off

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

Redirect URLs for Acme Assistant: https://assistant.acme.example/oauth/callback in the ringed box, where the person is sent back after they allow or deny, and Add redirect URL

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

The Agent readiness tab: How AI agents connect to your app, in three steps: Discover, Get a client, Consent, where the agent acts as that user and never beyond their permissions

In the Agent access card:

SettingWhat it does
Agent readinessPublishes where your users sign in, so an agent can find your OAuth 2.0 addresses by itself
Let agents register themselvesAgents 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 agentsEvery 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-signupSomething 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 emailAn 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 agentsThe 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.

The Agent access card with the Agent readiness switch ringed: Agent readiness, Allow agent self-signup, Let agents register themselves, Let agents register with a person's email, Let companies' identity providers approve agents and Let agents identify themselves by a metadata document, all off, and 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.

Let agents register with a person's email, its switch ringed and turned on, and under it Agent client for registered agents, which issues the tokens to one of your agent clients with the device code grant on

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.

The Agent client for registered agents picker open, with Acme Assistant, the one agent client with device code on, ringed

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.

The discovery addresses agents read: the authorization server metadata, the issuer, and the client registration endpoint, each with a copy button

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.

The clients on the Settings tab, with the Type column ringed: Acme CLI and Acme Assistant read OAuth 2.0 provider, cut short by the column, and Acme sample app and Acme Analytics read App sign-in, each with its masked client ID and secret

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.

Let agents identify themselves by a metadata document, its switch ringed and turned on, with Base client for agents identified by a metadata document, Most agents kept, Vetted document hosts and What stands in for a secret under it

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

Vetted document hosts with claude.ai typed in its box, which is ringed

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

Most agents kept with 200 typed in its box, which is ringed

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.

The Settings tab with Metadata document picked in the Source filter: one client, Notes Agent, with a View button instead of Edit, and its Type, Agent, identified by notes-agent.example, ringed

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:

ScopeThe consent screen says
openidConfirm who you are
profileSee your name and profile
emailSee your email address
offline_accessStay 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)
  1. In the BuildBase console, press Users in the left-hand bar, then Authentication under Access, and the Agent readiness tab.
  2. 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).
  3. 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.
  4. Press Save scope descriptions. The next consent screen uses them; nothing needs a redeploy.

The Scope descriptions card on the Agent readiness tab, 2 of 50: notes:read described as See your notes and the folders they are in, and notes:delete described as Delete your notes, which cannot be undone, with Sensitive ticked; Save scope descriptions ringed

What the consent screen shows for each scope an agent asks for:

The scopeThe consent screen shows
A standard one (openid)The words in the table above, in the person's language
One you describedYour description, with the scope name in small text under it
One you described as sensitiveThe same, with a warning and the word Sensitive
One you did not describeThe 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.

Acme Assistant wants to access your account: it will act as you, limited to the permissions below and to what your role allows, see your account ID and role, your email address and whether it is verified, your name and profile picture, and whether your account is blocked, and stay connected until you disconnect it or it goes unused for 30 days; it asked for openid, profile, email and offline_access, said in words, notes:read as See your notes and the folders they are in, and notes:delete as Delete your notes, which cannot be undone, marked Sensitive; after you answer you go back to assistant.acme.example; Allow access and Deny, both ringed

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:

Notes Helper, an agent that registered itself, wants to access your account, with a warning that the app gave itself its name and nobody has checked it, the same list of what it gets, openid and profile in words and notes:read in Acme's words, See your notes and the folders they are in, where you go back to (notes-helper.example), and Allow access and Deny, both ringed

On a phone:

The consent screen on a phone for Notes Helper: the unchecked-name warning, the whole list of what it gets, the permissions it asked for in words, where you go back to, then Allow access and Deny, both ringed

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.

The Connected agents screen in the app: Acme Assistant and Notes Helper, each with the access it was given, when, and a Disconnect button

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

The question Disconnect asks: "Disconnect Acme Assistant? It loses access to your account at once. You can connect it again at any time." with Cancel and Disconnect

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.

Connected agents after Disconnect: a banner says Acme Assistant was disconnected, and only Notes Helper is left

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_token your 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:// to https://, fails with 503 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-id header (<orgId>-<key> for an environment, the org id alone for production) is refused with 401 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 seeWhyWhat to do
No consent screen; the agent gets a code straight awayThe client is Application (first-party), or the person already allowed this agent everything it asks forChoose Agent (third-party). To ask again, the person disconnects the agent
error=invalid_request, "code_challenge is required (PKCE)", at the redirect URLRequire PKCE is on and the request has no code_challengeSend a PKCE pair, as every agent should
"Connecting new agents is not available right now."Your plan's limit on connected agents is reachedRaise 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 tokenCheck the route is reachable and checks with this client's secret
400 invalid_grant, "Invalid refresh token"The person disconnected the agentThe agent asks the person to connect again
The agent cannot register itselfLet agents register themselves is off, or no base client is pickedTurn it on and pick a base client on the Agent readiness tab
A scope shows its bare name instead of your wordsIt 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_MISMATCHThe agent's token was issued in another environment than the one the request namesConnect the agent again from the environment your MCP server is set up for

Next steps