OAuth2

The Airwallex OAuth 2.0 API allows your applications to access other Airwallex clients' resources on behalf of the client by implementing the OAuth 2.0 protocol . Airwallex currently supports the authorization code grant type using the standard authorization code flow and the Proof Key for Code Exchange (PKCE) extension .

Airwallex OAuth 2.0 API consists of two endpoints:

An authorization endpoint for obtaining the authorization_code.
A token endpoint for exchanging the authorization_code or refresh_token for an access token.

Once an access token is obtained, you may call the Airwallex APIs on behalf of the client by setting the Authorization header in every API request (e.g. Authorization: Bearer <access token>). Only the APIs corresponding to the scopes set in the authorization request will be allowed access. To use the Airwallex OAuth 2.0 API, you will need to register your application by contacting [email protected]. The client_id and client_secret are issued upon successful registration.

Endpoints

GET /oauth/authorize
POST /oauth/token

Authorization

GET /oauth/authorize

Copy for LLMView as Markdown

Your client-side applications (i.e. web, desktop or mobile applications) should redirect the user to this endpoint in order to initiate the authorization flow. If your application(s) are able to securely store client secrets in the application server, then your application may use the standard authorization code flow using the following request:

https://airwallex.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENTID &redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPE&state=YOUR_STATE

The PKCE flow is required for applications like desktops and mobile apps that cannot securely store client secrets. Your application should generate both the code_verifier and code_challenge before the authorization request, using the method described in the RFC 7636 Section 4 . They are used to compose the authorization request as follows:

https://airwallex.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENTID &redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPE&state=YOUR_STATE &code_challenge=YOUR_GENERATED_CODE_CHALLENGE&code_challenge_method=S256

This endpoint asks the user to sign into the Airwallex webapp with his/her login credentials and requests the user to authorize your application to make API requests on behalf of the user.

If the user accepts the authorization request, the user is redirected to your application specified by redirect_uri, along with the response code and state in the URL. A successful authorization redirects the user to following URL:

https://your-website.com/callback?state=YOUR_STATE&code=AUTH_CODE

If the user rejects the authorization request, the user is redirected to your application specified by redirect_uri, along with error=access_denied and state in the URL.

In case that any request parameters are missing or incorrect, the user will be redirected to redirect_uri with parameters state and error. The response body contains detailed error information as described in the Errors section below. An unsuccessful authorization will be redirected to following URL:

https://your-website.com/callback?state=YOUR_STATE&error=ERROR_CODE

An error will be shown in the consent screen if the client_id and redirect_uri are invalid.

Query parameters

client_idrequiredstring

The ID of your application issued by Airwallex.

Please contact [email protected] to have a client_id assigned for your application.

redirect_urirequiredstring

The URI to redirect the users to the user either accept or reject the authorization.

It must match any of the pre-registered URIs for your application.

response_typerequiredstring

Only the authorization code workflow is supported. Value must be set to code.

code

scoperequiredstring

The OAuth scopes that indicate the resources your application is allowed to access.

The value should be expressed as a list of space-delimited, case-sensitive strings. Only scopes pre-registered with your application are allowed. You should request the minimum scopes required for your application. The complete list of scopes can be found in the Scopes section.

code_challengestring

A challenge token generated together with the code_verifier by your application with the detailed generation method described in RFC 7636 Section 4 . Mandatory for PKCE flow.

code_challenge_methodstring

A method used to generate the code_challenge. Value must be set to S256.

S256

statestring

A value included in the request that is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing CSRF attacks.

The value can also encode information about the user's state in the app before the authentication request occurred. For instance, it could encode the page or view they were on.

Response body - 200 OK

codestring

The authorization code generated by Airwallex. It is used to exchange tokens in the token endpoint. The authorization code expires in 5 minutes and becomes invalid once an access token is exchanged.

statestring

The state value as specified in the request. Only accept the authorization response as genuine if it matches the value you have stored earlier, else deny it.

Errors

Error status	Description
401	Unauthorized
403	Forbidden
429	Too many requests

GET /oauth/authorize

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/oauth/authorize' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Was this section helpful?

Obtain an Access Token and Refresh the Token

POST /oauth/token

Copy for LLMView as Markdown

Obtain an access token and refresh the token pair. The grant_type parameter determines which flow to use:

authorization_code: Use this after the user completes the authorization flow. Pass the authorization code you received to obtain your first access token and refresh token. Store the refresh token securely for later use.

refresh_token: Use this when your access token has expired or is about to expire. Pass the latest refresh token to obtain a new access token and refresh token pair.

Refresh token handling

Each successful refresh request returns a new access token and a new refresh token. Refresh tokens are rotated on every use: only the latest one is valid, and the previous one must not be reused for normal refresh requests. Do not send concurrent refresh requests for the same user or session; they are not supported.

Refresh tokens expire after the period indicated by the refresh_token_expires_in field. Each refresh token must be used at least once within that window to keep the authorization active, and every successful use resets the expiry. If a refresh token is lost or has expired, it cannot be recovered and the user must re-authorize your application.

Retrying a failed refresh request

Handle a failed refresh request according to the response status:

5xx (server error): Retry the request immediately using the same refresh token. The original request may not have completed, and a new token pair may or may not have been issued.

For up to 1 minute after a new refresh token is issued, the previous refresh token remains valid and returns the same new token pair without rotating it again. This allows an immediate retry to recover from a lost response or a transient server error.

Do not delay the retry (for example, by scheduling it minutes or hours later), as doing so may cause you to miss the 1-minute grace period.

429 (too many requests): Wait before retrying the request with the same refresh token.
Any other 4xx (client error): Stop retrying. The refresh token is permanently invalid, for example, because it has already been consumed and the grace period has expired, the token has expired, the account has expired, or the user has revoked the authorization.

Retrying the request with the same refresh token will always return the same error. Instead, mark the connection as disconnected or unauthorized and wait for the user to re-authorize your application.

Request body

Returns an empty JSON object

Response body - 200 OK

access_tokenstring

The access token issued by Airwallex. It is used for authorizing an Airwallex API request.

account_idstring

The unique identifier of the authorized Airwallex account. This is useful to identify the associated account in the webhook events.

expires_ininteger

The lifetime of the access token since it was generated (in seconds).

org_idstring

The ID of the authorized Airwallex organization. Only returned when Spend or Billing scopes are authorized. This is useful to identify the associated organization in the webhook events.

refresh_tokenstring

The token that you can use to obtain a new access token.

refresh_token_expires_ininteger

The lifetime of the refresh token since it was generated (in seconds).

scopestring

The authorized scopes of the access token.

token_typestring

The type of the token issued. Value must be bearer.

bearer

Errors

Error status	Description
400	Some parameters were invalid, as specified by Errors.
401	Client authentication failed
429	Too many requests
500	The server encountered an unexpected condition that prevented it from fulfilling the request.

POST /oauth/token

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/oauth/token' \
>  --header 'Authorization: Basic YXBwaWRfYzRmN2UyYTFiOGQzZjZlOTpSZnQzeUtwWHZROG1Od0xzNkJjWmpBMmhVZEVvN0d4SQ==' \
>  --header 'Content-Type: application/x-www-form-urlencoded' \
>  --data-urlencode 'grant_type=authorization_code' \
>  --data-urlencode 'code=SplxlOBeZQQYbYS6WxSbIA' \
>  --data-urlencode 'redirect_uri=https://example.com/callback' \
>  --data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r'

Response (200 OK)

1{
2  "token_type": "bearer",
3  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc...",
4  "expires_in": 300,
5  "refresh_token": "8xnR-quBvNkLwP5tdmOA9yMXpJ3zTrjF",
6  "refresh_token_expires_in": 7776000,
7  "scope": "balance:read transfer:write",
8  "account_id": "acct_d8e9f0a1b2c3d4e5f6a7b8c9",
9  "org_id": "org_a1b2c3d4e5f6a7b8c9d0e1f2",
10  "grant_id": "gnt_sgpd5k6pgfub17f8gy8"
11}

Was this section helpful?

Errors

Copy for LLMView as Markdown

If the authorization request failed due to invalid redirect_uri or client_id, Airwallex will display an error page instead of redirecting the user back to your application, and you will not receive an authorization response in this case. For all other unsuccessful cases, Airwallex server informs the application by adding the following error parameters to the fragment component of the redirection URI using the application/x-www-form-urlencoded format.

If the token exchange request failed, Airwallex will return an HTTP status code defined in the API spec, along the following error parameters in the response:

Response body

errorstring

The error code. Refer to the Error Codes table for all possible values.

error_descriptionstring

Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred

error_uristring

A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error

Error codes
access_denied	The account owner denied the request.
invalid_request	The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating your application, or is otherwise malformed.
invalid_client	Client authentication failed
invalid_grant	The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another application.
unauthorized_client	Your application is not authorized to use this authorization grant type.
unsupported_grant_type	The authorization grant type is not supported.
unsupported_response_type	The server does not support obtaining an access token using this method.
invalid_scope	The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
server_error	The server encountered an unexpected condition that prevented it from fulfilling the request.
temporarily_unavailable	The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Response (400 Bad request)

1{
2  "error": "invalid_request",
3  "error_description": "OAuth 2.0 Parameter: client_id",
4  "error_uri": "https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1"
5}

Was this section helpful?