Implement your authorization flow
Use this step-by-step guide to implement your authorization flow.
Step 1: Allow Airwallex customers to authorize your application
On your user interface, implement a “Connect to Airwallex” button that your users can click on to connect their Airwallex account to your application. This button should open our OAuth authorization flow URL: https://airwallex.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENTID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES
You must enumerate all the scopes in YOUR_SCOPES that you intend to access through the integration in the authorization flow. The authorization flow is required when users connect to your application for the first time. It is also required when your application needs to access additional scopes.
Customers will be taken to login to their Airwallex account, select which account they want to connect to your application, and review the relevant permissions that you are requesting.
If they give consent for your application to access their Airwallex account, Airwallex will redirect users back to YOUR_REDIRECT_URI with an authorization code. Otherwise, Airwallex will redirect back to YOUR_REDIRECT_URI with an error.
https://YOUR_REDIRECT_URI/?code=AUTH_CODE
Redirect URIs must be whitelisted for security purposes; if you intend to add a new redirect URI, contact your Airwallex partnerships manager to do so. Attempting to use a non-whitelisted redirect URI will result in an error.
Step 2: Obtain refresh and access tokens
Once the authorization code is successfully obtained, your application should exchange the authorization code back to Airwallex OAuth server for a refresh and access token.
Note that YOUR_REDIRECT_URI must match the one that was used to obtain the AUTH_CODE in the previous step.
If the AUTH_CODE is valid, you will receive a refresh and access token. The refresh token is long-lived (valid for 60 days), and you should store this securely in a database for refreshing your access token later. The access token is short-lived (valid for 5 minutes) and should be used in each session where you call the Airwallex API on behalf of authorized accounts.
To use the access token, pass the access token value in the Authorization header of requests each time your application calls an API. The value should always be: Authorization: Bearer {AccessToken}. For example, you can now call the GET /api/v1/account/ endpoint to obtain details about the account that was just connected.
Step 3: Refresh access tokens
As the access token is short-lived, you will need to obtain new access tokens to continue accessing the Airwallex API across sessions. To do so, use the latest refresh token value from your previous call to /oauth/token/.
This will give you a new access token and refresh token. You should replace the previously-stored refresh token value with the new one, as the old refresh token value is no longer valid.
Do not attempt to use old refresh tokens to obtain a new access token. Doing so will cause the connection to be invalidated, as Airwallex interprets that as a potential signal that your refresh tokens were leaked or compromised by a third party.
Access tokens may become invalid if:
- The access token is expired: You will need to use your refresh token to renew the access token
- Your user revoked access: If a user disconnects their Airwallex account from your application, it invalidates the access token and refresh token. You will need to ask your users to start the authorization flow again