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-api.brex.com/oauth2/default/v1/authorize?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. 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:

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

POST https://accounts-api.brex.com/oauth2/default/v1/token

Request body:

grant_type: "authorization_code"
code: "<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.

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:

POST https://accounts-api.brex.com/oauth2/default/v1/token

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.