# Authentication via OAuth + OpenID Connect Brex API authentication is fully compliant with OpenID Connect, an extension on top of OAuth2. For more details on the OpenID Connect protocol see the spec [here](https://openid.net/specs/openid-connect-core-1_0.html). The well-known configuration can be found at the following urls: **Production:** [https://accounts.brex.com/.well-known/openid-configuration](https://accounts.brex.com/.well-known/openid-configuration) **Staging:** [https://accounts.staging.brexapps.com/.well-known/openid-configuration](https://accounts.staging.brexapps.com/.well-known/openid-configuration) ## Scopes You will need to request the following scopes to access the API: `openid` `offline_access` `https://accounting.brexapis.com/cash` `https://accounting.brexapis.com/card` For the `/cards` endpoint, the additional scope `https://corpcard.brexapis.com/cards.readonly` is required. ## Example Auth Flow The current base url for these requests is **Production** `https://accounts.brex.com/oauth2/v1` **Staging** `https://accounts.staging.brexapps.com/oauth2/v1` This may change in the future so be sure to check the openid-configuration. ### 1. Authorize ``` curl /auth?prompt=consent&client_id=&response_type=code&redirect_uri=&scope=&state= ``` Note: * `state` is a required parameter and 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](https://oauth.net/2/pkce/) is also supported, but not required. This will return an authentication code to be used for obtaining a token in step 2: ### 2. Authorization grant **Request** ``` curl --url '/token' \ --data 'code=' \ --data 'client_id=' \ --data 'client_secret=' \ --data 'grant_type=authorization_code' \ --data 'redirect_uri=' ``` Note: * To obtain a `refresh_token`, make sure you've included the parameter `prompt=consent` and requested the `offline_access` scope in step 1. * To obtain an `id_token`, make sure you've requested `openid` scope in step 1. * if OAuth2 PKCE flow is used, then `client_secret` is not required; instead `code_verifier` is required. **Response** ``` { access_token: , expires_in: 3600, token_type: Bearer, refresh_token: , scope: , id_token: } ``` The access token expires in 3600 seconds (1 hour) ### 3. Refresh token To obtain a new access token, pass in the `refresh_token` value from the step above, and `grant_type=refresh_token`. Note: Always use the new refresh token! We are transitioning into a strict rotation scheme. **Request** ``` curl --url '/token' \ --data 'refresh_token=' \ --data 'client_id=' \ --data 'client_secret=' \ --data 'grant_type=refresh_token' \ --data 'redirect_uri=' \ ``` The response will contain a new `access_token` as well as a new `refresh_token`. **Response** ``` { "access_token": , "expires_in": 3600, "id_token", , "refresh_token": , "token_type": "Bearer" } ``` ## Calling the API **Production endpoint:** [https://platform.brexapis.com/v1](https://platform.brexapis.com/v1) **Staging endpoint:** [https://platform.staging.brexapps.com/v1](https://platform.staging.brexapps.com/v1) The primary serialization format for this API is JSON. After an access token is made available with the appropriate scopes, it should be passed in the HTTP headers as follows: ``` Authorization: Bearer ``` ### Example usage **New customer setup** Get accounts via `/accounts` ``` https://platform.brexapis.com/v1/accounting/accounts ``` Get historical data ``` https://platform.brexapis.com/v1/accounting/accounts/{account_id}/transactions?start_time={2 years ago} ``` **Daily pulls** Get accounts via `/accounts` ``` https://platform.brexapis.com/v1/accounting/accounts ``` Get historical data ``` https://platform.brexapis.com/v1/accounting/accounts/{account_id}/transactions?start_time=2020-06-01T00:00:00Z ``` Get transactions in a given statement ``` https://platform.brexapis.com/v1/accounting/accounts/{account_id}/transactions?statement_id=pst_ckahg2dml029n01t9plk2abc4 ``` # Pagination All the endpoints below will return a maximum of **100** results at a time. For pagination, we will expose a `next_cursor` token in the list of results. ``` { "items": [ { ... }, { ... } ], "next_cursor": "bGltaXQ9MjAmb2Zmc2V0PTE" } ``` To request the next page, append `cursor=` to the request URL. If you pass in a cursor, you do not need to pass in any additional parameters (the parameters of your original query will be automatically used). If there are no more results, the `next_cursor` will be `null`. **Example** ``` https://platform.staging.brexapps.com/v1/accounting/accounts/{accountId}/transactions?cursor=bGltaXQ9MjAmb2Zmc2V0PTE ``` # Tracing The API returns a Brex trace ID in the response header, `X-Brex-Trace-Id` which can be used for debugging and observability.