Launch Checklist

Let's make sure your team and Brex integration are ready for production launch. Before development and before launch, we recommend going over the following items to ensure a production-ready, secure, and robust integration. Most of these items are elaborated in more detail throughout the docs, but are consolidated here for convenience.

For Customers

Pre-development

Development

  • Your Brex integration should implement the latest endpoints documented in the API reference. You can explore these endpoints with Postman as well. Keep an eye on the changelog for updates.
  • Use environment variables to replace secrets in your source code. Namely, do not expose your user token in code and make sure it's not checked into version control.
  • Your code should be able to generate random strings for the Idempotency Key . We require an idempotency key for endpoints where erroneous duplicate processing would be especially bad, such as Create transfer and Create card .
  • As stated in Versioning , your code should be able to handle new types of JSON responses. For example, please ensure that you design your code to handle unknown enum types and new response fields.
  • If you get stuck, review error codes and recommended fixes .
  • Ensure your integration can gracefully handle rate limits , even if you believe you won't come up against them.
For Partners

Pre-development

Development

  • Your Brex integration should implement the latest endpoints documented in the API reference. You can explore these endpoints with Postman as well. Keep an eye on the changelog for updates.
  • Use environment variables to replace secrets in your source code. Namely, do not expose any client_id s and client_secret s and ensure they are not checked into any version control.
  • Your code should be able to generate random strings for the Idempotency Key . We require an idempotency key for endpoints where erroneous duplicate processing would be especially bad, such as Create transfer and Create card .
  • We recommend using an existing OAuth 2.0 library to implement the OAuth 2.0 Authorization Code Grant for partner integrations: https://oauth.net/code/ .
  • For partner integrations, note that the access token expires in 3600 seconds (1 hour) and will need to be refreshed every time after it expires.
  • To mitigate cross-site request forgery , partner integrations should always use the optional state parameter when initiating the OAuth 2.0 Authorization Code Grant. The value of your state parameter must be a random string, at least 9 characters long. Whatever string value you provide for the state parameter will be returned when the customer is redirected to your integration. At that moment, your integration should check if the returned state value matches the original state value that you set on the initial authorization request. If the values do not match, this means that someone else has initiated the authorization request.
  • Partner integrations should always rotate the refresh_token . Whenever your integration exchanges a refresh token for a new access token, it should retain both the new access token and the refresh token (which is returned in the same response).
  • During the authorization flow, partner integrations should not load the authorization page inside a native web view or iFrame. Please launch a browser instead.
  • As stated in Versioning , your code should be able to handle new types of JSON responses. For example, please ensure that you design your code to handle unknown enum types and new response fields.
  • After your integration has initiated the authorization request, the customer has the option to grant or deny access. You should handle each scenario gracefully.
  • You should anticipate errors involving insufficient scopes and/or permissions. Scopes define what your integration can access. Permissions define what the customer can access. More precisely, scopes define which API endpoints your integration can access, but permissions are based on the customer ' s role type . The role type defines which actions a customer can perform on the Brex dashboard and, consequently, the Brex APIs. So, it ' s possible for your code to fail if:
    • Your integration relies on Brex resources that the customer ' s role type forbids
    • The customer denies access during the authorization flow
    • The customer grants insufficient scopes for their user token
    • Your integration targets Brex Cash, but the customer has not enabled Brex Cash
  • If you get stuck, review error codes and recommended fixes .
  • Ensure your integration can gracefully handle rate limits , even if you believe you won't come up against them.
  • Once you've built your integration, be sure to share a demo video with us.
Copyright © Brex 2019–2022. All rights reserved.