Skip to content

Manage OAuth settings

OAuth settings manage company-wide access to OAuth Partner Apps and the Braze MCP server. Use them to approve or block partner apps by workspace, control which MCP clients and redirect URIs can connect to Braze, and revoke every MCP OAuth token for your company.

OAuth settings apply to your entire company. The permissions assigned to each user determine which workspaces and features they can access through partner apps and the MCP server.

Requirements

Requirement Description
“Admin” permission You must have the company-level “Admin” permission to view OAuth settings, manage OAuth Partner Apps, turn MCP OAuth access on or off, approve or remove MCP clients, manage redirect URIs, or revoke MCP OAuth tokens.
“Use MCP Server” permission Users must have this permission for each workspace they want to access through the MCP server. This permission is separate from the “Admin” permission used to manage OAuth settings.

For more information about assigning permissions, see User permissions.

How OAuth access works

OAuth settings and user permissions work together:

  • Company-wide OAuth settings determine whether users can connect partner apps and MCP clients to Braze.
  • OAuth Partner Apps policies determine which partner apps are approved or blocked in each workspace.
  • The “Use MCP Server” permission determines whether an individual user can use the MCP server in a workspace.
  • The user’s existing dashboard permissions determine which Braze data and features an MCP client or partner app can access.
  • One OAuth connection can access only the workspaces that the user is authorized to access.

Turning on MCP OAuth access or Partner apps OAuth access doesn’t grant users new workspace permissions. Similarly, removing a dashboard permission removes that capability from the user’s connected client or partner app.

Company and workspace controls

OAuth policy is stored at the company level. Workspace admins can’t override Partner apps OAuth access, MCP OAuth access, or redirect URI statuses for a single workspace. Partner app approval can still limit access to selected workspaces.

Control Where you configure it Scope
Partner apps OAuth access and OAuth Partner Apps Settings > Admin Settings > External Connections Company-wide enablement on the OAuth Settings tab, with approved or blocked status per partner app and selected workspaces on the OAuth Partner Apps tab.
MCP OAuth access External Connections > OAuth Settings Entire company. When this is off, MCP OAuth is denied in every workspace.
MCP Clients page External Connections > MCP Clients Entire company. Approving a verified client allows users with “Use MCP Server” to connect it in every workspace.
Approved redirect URIs External Connections > MCP Clients Entire company. Custom (and local) redirect URIs apply to all workspaces.
Revoke MCP OAuth tokens External Connections > OAuth Settings Entire company. Revocation applies to every MCP OAuth token in every workspace.
“Use MCP Server” permission Settings > User Management Per workspace. Users need this permission in each workspace they access through the MCP server.

Only users with the “Admin” permission can change partner app policies, change MCP OAuth access, approve or remove MCP clients, change redirect URI statuses, or revoke MCP OAuth tokens. For how workspace permissions interact with these company settings, see OAuth and MCP access.

OAuth Partner Apps

Use the OAuth Partner Apps tab to monitor and manage which partner apps your company users can connect with OAuth:

  1. Go to Settings > Admin Settings > External Connections.
  2. Open the OAuth Partner Apps tab.

View partner apps

The Partner Apps list shows every OAuth partner app your company has approved or blocked. For each app, you can review:

Column Description
App name The partner app name.
Last updated by The dashboard user who last changed the partner app policy.
Last updated When the partner app policy was last changed.
Approved workspaces The workspaces where company users can connect the app.
Status Whether the app is Approved or Blocked.

Browse and approve partner apps

To approve a partner app for your company:

  1. On the OAuth Partner Apps tab, select Browse apps.
  2. Select the partner app you want to review.
  3. Select Approve app, then choose all workspaces or selected workspaces.
  4. Select Approve.

By default, all workspaces are approved. Company users can connect the app only to workspaces you approve. You can select Edit workspaces later to change workspace access.

Review app details

Open a partner app to view its App details, including the app description and permission scopes. Each user can only perform actions allowed by their own Braze permissions.

Block a partner app

To stop users from connecting a partner app in selected workspaces:

  1. Open the partner app from the Partner Apps list or Browse apps.
  2. Select Block app, then choose the workspaces to block.
  3. Confirm the action.

Users in those workspaces are disconnected immediately and can no longer sign in or sync with that app. You can approve the app again at any time.

Turn Partner apps OAuth access on or off

Partner apps OAuth access is a company-wide switch on the OAuth Settings tab.

  1. Go to Settings > Admin Settings > External Connections.
  2. Open the OAuth Settings tab.
  3. In Global access controls, turn Partner apps OAuth access on or off.

When Partner apps OAuth access is on, admins can manage partner apps on the OAuth Partner Apps tab, and company users can connect approved partner apps in approved workspaces. When it’s off, Braze immediately disconnects partner app OAuth access for all users and ends active sessions. Data already synced through these integrations stays in Braze. If you turn Partner apps OAuth access back on, existing connections work again.

Braze Bonfire Community

Braze Bonfire Community appears as an app under Settings > Admin Settings > External Connections > OAuth Partner Apps. This defaults to approved.

Users can open Community in the dashboard and select Sign in to Braze Bonfire Community to sign in with their Braze account.

Different Braze dashboard and Bonfire account emails

If you sign in with a different email than your existing Bonfire account, a new Bonfire account is created. To merge your previous posts, email [email protected] from both email addresses to confirm ownership.

Turn MCP OAuth access on or off

To update MCP OAuth access for your company:

  1. Go to Settings > Admin Settings > External Connections.
  2. In Global access controls, turn MCP OAuth access on or off.

When MCP OAuth access is on, users with the “Use MCP Server” permission can authorize approved MCP clients. When it’s off, OAuth access to the MCP server is denied for all users and workspaces in your company, and the MCP Clients tab is unavailable.

Turning off MCP OAuth access doesn’t remove or block your configured redirect URIs. Braze revokes existing MCP OAuth tokens for your company, so connected MCP clients lose access.

Manage MCP clients

The MCP Clients tab is where you control which Braze-verified MCP clients your users can connect, and where you manage custom redirect URIs for clients that aren’t on Braze’s verified list.

Verified MCP clients

Braze pre-registers a set of verified MCP clients so you can approve them by name instead of pasting redirect URIs. After you approve a client, it appears under Verified MCP clients with an Approved status:

  • ChatGPT
  • Claude
  • Claude Code
  • Cursor
  • OpenAI Codex
  • Visual Studio Code

Browse and approve a verified client

  1. Go to Settings > Admin Settings > External Connections.
  2. Confirm MCP OAuth access is on under OAuth Settings.
  3. Open the MCP Clients tab.
  4. Select Add MCP client > Browse verified MCP clients, or select Browse MCP Clients if you haven’t approved any clients yet.
  5. Search or filter the list, then open the client you want to allow.
  6. Review the client’s details and supported experiences (for example, web, desktop, or terminal), then select Finish setup.

Some clients connect only through local addresses on each user’s computer (such as http://localhost/... or a custom scheme). Local addresses aren’t unique to one app, so other apps that use the same address can also reach Braze after you approve it. When you approve a client that needs local addresses, Braze may ask you to approve those addresses at the same time. You can remove the client or change URI status later.

MCP client statuses

Status Meaning
Not approved Your company hasn’t approved the client yet. The client isn’t on your approved list, and users can’t connect it.
Approved Users with the “Use MCP Server” permission can connect this client. None of the client’s redirect URIs are blocked.
Partial access The client is approved, but one or more of its redirect URIs are Blocked in the redirect URI table. Users can still connect through the client’s remaining approved addresses.
No access The client is approved, but every one of its redirect URIs is Blocked. Users can’t connect the client until you unblock at least one address.

Remove a verified client

To take a verified client off your approved list, open the client from the MCP Clients tab and select Remove MCP client. Users can’t connect that client again until you approve it from Browse verified MCP clients.

Removing a client doesn’t end sessions for users who are already connected. Select Revoke MCP OAuth tokens to end those sessions.

Manage custom redirect URIs

After you turn on MCP OAuth access, the Approved redirect URIs section on the MCP Clients tab lists custom redirect URIs for local MCP clients or remote clients that Braze hasn’t verified. Use this list when a client isn’t available among the verified MCP clients. For formatting guidance, see Redirect URI formats.

You can also select Add MCP client > Add custom redirect URIs to add URIs without browsing verified MCP clients.

The Approved redirect URIs table shows the following information:

Column Description
Redirect URI The exact address Braze matches against the client’s callback, including the path.
Added by The dashboard user who added or last updated the URI.
Date added When the URI was added or last updated.
Status Whether the URI is Approved or Blocked.
Actions Block, Unblock, or Delete redirect URI, depending on the current status.

Redirect URI formats

URI type Format to use when adding
Local (loopback address) Starts with http://localhost or http://127.0.0.1. Omit the port (the colon and numbers after the host) so any local port can match. For example, if the client shows http://localhost:33491/oauth/callback, enter http://localhost/oauth/callback. If you keep a port in the URI you add (such as :33491), Braze matches that port only.
Remote address Enter the full address exactly as the client shows, for example https://app.example.com/callback.
Custom scheme Starts with a custom URI scheme (not http:// or https://), such as cursor://. Enter it exactly as shown. Some desktop apps use these addresses.

Add a custom redirect URI

To allow an MCP client that isn’t a Braze-verified MCP client:

  1. Open the MCP Clients tab, then select Add MCP client > Add custom redirect URIs, or select Add redirect URI in the Approved redirect URIs section.
  2. Enter the full redirect URI with callback protocol from the client’s OAuth or integration settings. Use the Redirect URI formats table if you need help matching the client’s callback.
  3. Select Save.

For local clients, use 127.0.0.1 and omit the port number in the redirect URI you add.

Only redirect URIs with an Approved status can complete a new OAuth authorization for custom clients. If a client’s redirect URI isn’t on the list, or its status is Blocked, Braze denies the authorization request. For Braze-verified clients, prefer approving the client on the MCP Clients page instead of adding URIs by hand.

Block a redirect URI

To prevent new OAuth authorizations from a redirect URI, select Block for its row and confirm the action. Braze retains the URI record and changes its status to Blocked.

Blocking a redirect URI doesn’t revoke tokens for users who are already connected to that MCP client. Select Revoke MCP OAuth tokens to end those sessions. Blocking the URI is a separate action that prevents new authorizations with that callback.

Alternatively, remove the “Use MCP Server” permission from a user to stop only that user from using the MCP server. Other users’ MCP connections stay active until you select Revoke MCP OAuth tokens.

Unblock a redirect URI

To restore access for a blocked redirect URI, select Unblock for its row and confirm the action. Braze updates the existing record to Approved instead of creating a duplicate.

Users who were previously connected to that MCP client need to authenticate again.

Delete a redirect URI

To remove a redirect URI from the Approved redirect URIs list, select Delete redirect URI for its row and confirm the action.

  • If the URI was Approved, approved marketplace clients that use that address can still connect through it. Other apps that relied only on the custom list entry can no longer use it. To stop approved clients from using the address as well, block the URI instead of deleting it.
  • If the URI was Blocked, deleting it removes the block. Approved clients and other apps that use the address can connect through it again. To keep the address blocked, leave it on the list.

Deleting a redirect URI doesn’t revoke tokens for users who are already connected. Select Revoke MCP OAuth tokens to end those sessions.

Revoke MCP OAuth tokens

Revoking tokens invalidates every MCP OAuth token across your company at once. Use this if you think a token has been leaked or misused.

To revoke your company’s MCP OAuth tokens:

  1. Go to Settings > Admin Settings > External Connections.
  2. In Revoke MCP OAuth tokens, select Revoke MCP OAuth tokens.
  3. Review the confirmation dialog, then select Revoke tokens.

Braze revokes the tokens in the background and shows a confirmation message when the revocation finishes. For companies with many connections, this can take a few minutes. Leave the External Connections page open until the confirmation appears.

What revocation changes

Item Result
Access tokens Revoked. Connected MCP clients stop working until the user reconnects.
Refresh tokens Revoked. MCP clients can’t reconnect on their own in the background. Users have to reconnect themselves.
MCP OAuth access Unchanged. If it was on, users can reconnect right away.
Approved redirect URIs Unchanged. Approved and blocked URIs stay as they are.
“Use MCP Server” permission Unchanged. Users keep the permission and can reconnect.
New connections Unaffected. Connections made after you start the revocation keep working.

Requests that were already in progress when you revoked aren’t recalled. To stop all MCP access instead of only ending current sessions, turn off MCP OAuth access (that also revokes MCP OAuth tokens). To remove one user’s MCP access, remove the “Use MCP Server” permission from that user.

If revocation doesn’t finish, Braze shows an error message. Some tokens may already be revoked, so contact support before trying again.

Troubleshoot blocked connections

If a user sees “This app needs approval” or a generic error such as “An unexpected error occurred” when they connect an MCP client to Braze, your company may not have approved that client or its redirect URI.

  1. Go to Settings > Admin Settings > External Connections > MCP Clients.
  2. If the client is Braze-verified, open it from Verified MCP clients or Browse verified MCP clients. Approve it if it isn’t on your approved list, including any local addresses it requires.
  3. If the client isn’t verified, find its redirect URI in the Approved redirect URIs table. Add the URI if it isn’t listed, or select Unblock if its status is Blocked.
  4. Ask the user to connect their MCP client again.

If the client or redirect URI is approved and the connection still fails, confirm that MCP OAuth access is on and that the user has the “Use MCP Server” permission. For more troubleshooting, see Setting up the Braze MCP server.

Audit OAuth activity

Braze records OAuth connections to the MCP server in the security event report. Use this report to audit when users connect through OAuth.

To revoke one user’s MCP access, remove the “Use MCP Server” permission from that user. To revoke every MCP OAuth token in your company, see Revoke MCP OAuth tokens. For setup and troubleshooting guidance, see Setting up the Braze MCP server.

New Stuff!