Partner authentication

Note: This section is only for Brex developer partners. If you are a Brex client–i.e., you have your own Brex account–looking to authenticate to our APIs, refer to the authentication page to get started.

The Brex API is fully compliant with OpenID Connect, an extension on top of OAuth 2.0. For more details on the OpenID Connect protocol, please see the spec. The well-known configuration can be found at the following URLs:



API servers



Note: There are no availability guarantees in staging–data stored in staging environments may be purged at any time. Use staging for point-in-time testing only.


openid: Required to make an OpenID Connect request.

offline_access: Required to obtain an OAuth 2.0 Refresh Token.

The scopes page describes how scopes work in the Brex API and the scopes required for each API.

Auth server

The base URL for the requests is:



This may change in the future without notice. Always use the openid-configuration as the source of truth for the base URL.

Authorization methods

Brex currently supports 2 different authorization grant types:

  • If you are using the onboarding API, you will generate a Client Credentials Grant as there is no existing Brex client involved.
  • For all other APIs, you will implement the Authorization Code Grant, which implements a web-based redirection flow to request permission from the Brex client to access their account. Only Brex clients with the proper roles may grant permission. Please see the User Roles & Permissions page for more details.

Authentication implementation

To implement authentication, we highly recommend using one of the existing OAuth 2.0 SDKs if available for your language. These SDKs handle the various intracies of the OAuth 2.0 spec and make it much easier to plug and play your credentials to get started.

Forcing OAuth login

If users of your application may have multiple Brex logins (for example, if users of your app are servicers like accountants or bookkeepers) you may wish to force the user to login to Brex every time they use your app. If desired, you can accomplish this by appending the prompt=login to the callback URL. See Authentication Request in the OpenID Connect spec for more details.

Implementing your own client

If you need to implement your own client, we recommend starting with the developer guides from Okta and reading below for more details.

Authorization Code Grant

1. Request authorization code

This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the Brex client’s web browser) and receiving API authorization codes that are routed through the user-agent.<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&scope=<SCOPES>&state=<STATE>


  • client_id=<CLIENT_ID>: The client id provided by Brex.
  • response_type=code: Specifies that your application is requesting an authorization code grant.
  • redirect_uri=<REDIRECT_URI>: Where the service redirects the user-agent after an authorization code is granted. Must match exactly one of the addresses that was provided to Brex when the credentials were set up.
  • scope=<SCOPES>: Scopes requested, separated by whitespaces.
  • state=<STATE>: A required parameter that must be longer than 8 characters. For more details about state parameter, please check
  • OAuth PKCE flow: Also supported, but not required.

2. The Brex client authorizes the application

When the browser link is opened, the Brex client will be prompted to sign in to authenticate their identity. They will then be prompted to authorize or deny your application's access to their account. They may accept 0 to all of the requested scopes which your application will then have access to. If they cancel consent, you will not have any scopes granted.

If the Brex client authorizes the request, we'll redirect the user-agent to your application's redirect URI, along with an authorization code. The redirect will look like this:



  • code=<AUTHORIZATION_CODE>: The authorization code that can be used to request an access token.
  • scope=<SCOPES>: Scopes that were granted by the Brex client and can be a subset of what was requested.
  • state=<STATE>: For security reasons, you should always confirm that the returned state matches the value you provided in the request.

3. Request an access token

To request an access token from the API, pass the authorization code along with authentication details to the API token endpoint. Here is an example request:


Request body:

grant_type: "authorization_code"
redirect_uri: "<REDIRECT_URI>"
client_id: "<CLIENT_ID>"
client_secret: "<CLIENT_SECRET>"

Response body:

access_token: "<ACCESS_TOKEN>"
refresh_token: "<REFRESH_TOKEN>"
token_type: "bearer"

The access token returned expires in 3600 seconds (1 hour) and you will need to get a new one (see step 5) every time after it expires. Getting a new access token does not require the user to re-authorize the request.

4. Using an access token

Add your <ACCESS_TOKEN> as a bearer token into the request header of any API calls you are making on behalf of the customer.

Request header:

Authorization: Bearer <ACCESS_TOKEN>

5. Getting a new access token and refresh token

To obtain a new access token, pass in the <REFRESH_TOKEN> previously obtained by the token endpoint, and set grant_type=refresh_token.

The response will contain a new <ACCESS_TOKEN> as well as a new REFRESH_TOKEN.

Refresh tokens expire every 90 days so they should be exchanged for a new one before then. Failure to do so will require the user to re-authenticate.

Client Credentials Grant

1. Request client credentials

Request an access token using grant_type=client_credentials and your Brex provided credentials from the token endpoint. Here is an example request:


Request body:

grant_type: "client_credentials"
client_id: "<CLIENT_ID>"
client_secret: "<CLIENT_SECRET>"
scope: "<SCOPES>"

Response body:

access_token: "<ACCESS_TOKEN>"
expires_in: <Seconds til expiry>
scope: "<SCOPES>"
token_type: "bearer"

2. Using an access token

Add your <ACCESS_TOKEN> as a bearer token into the request header of any API calls you are making on behalf of the customer.

Request header:

Authorization: Bearer <ACCESS_TOKEN>

The access token returned expires in 3600 seconds (1 hour). If you don't prefer to persistently store and rotate tokens, you can simply request a new token when it expired.

Revoking refresh tokens

Refresh tokens expire every 90 days. However, for general best security practices, or in the event of a compromise, you may want to revoke your refresh token. In order to do so, hit the refresh token revocation endpoint:

POST "{staging or production base URL}/oauth2/v1/token/revocation"

Request Body
  "token": "refresh-token-to-revoke",
  "client_id": "OAuth2 client id used to get the refresh token",
  "client_secret": "OAuth2 client secret used to get the refresh token"

Redirect URIs

Oauth 2.0 depends on Redirect URIs for the Authorization Code Grant. Partners must supply one or more redirect URIs that Brex will use to post the authorization code. (See Authentication implementation > Authorization Code Grant > 2. The Brex client authorizes the application)

Copyright © Brex 2019–2022. All rights reserved.