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:

Production: https://accounts.brex.com/.well-known/openid-configuration

Staging: https://accounts.staging.brexapps.com/.well-known/openid-configuration

API servers

Production: https://platform.brexapis.com

Staging: https://platform.staging.brexapps.com

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.

Scopes

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:

Production: https://accounts.brex.com/oauth2/v1

Staging: https://accounts.staging.brexapps.com/oauth2/v1

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

https://accounts.brex.com/oauth2/v1/auth?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&scope=<SCOPES>&state=<STATE>

Parameters:

  • 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 https://tools.ietf.org/html/rfc6749#section-10.12.
  • 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.

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:

<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&scope=<SCOPES>&state=<STATE>

Parameters:

  • 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 requests an access token from the API, pass the authorization code along with authentication details to the API token endpoint. Here is an example request:

POST https://accounts.brex.com/oauth2/v1/token

Request body:

grant_type: "authorization_code"
code: "<AUTHORIZATION_CODE>"
client_id: "<CLIENT_ID>"
client_secret: "<CLIENT_SECRET>"

Response body:

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

Note that the access token returned expires in 3600 seconds (1 hour) and will need to be refreshed every time after it expires. Refreshing a 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. Refresh token

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

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

Note: Always use the new refresh token! We are transitioning into a strict rotation scheme.

Client Credentials Grant

1. Request authorization grant

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

POST https://accounts.brex.com/oauth2/v1/token

Request body:

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

Response body:

access_token: "<ACCESS_TOKEN>"
refresh_token: "<REFRESH_TOKEN>"
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

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:

Copy
Copied
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–2021. All rights reserved.