Manage API keys
Airwallex uses your unique Client ID and API key to authenticate your API requests. You can use two types of API keys, admin API key and restricted API key.
This guide describes how to create, regenerate, and safely store your admin and restricted API keys.
Admin API key
The admin API key is a general purpose API key that allows you to access all Airwallex APIs.
You can only have one admin API key per account.
Generate admin API key for the first time
Use these steps to create an admin API key for your Airwallex account.
- Open Airwallex web app > Developer > API keys page.
- Click Generate API key.
- Enter your login password.
- Copy the API key and keep it in a secure place as you won't be able to view it on the web app again.
This will generate an admin API key that grants you access to all Airwallex APIs.
Regenerate admin API key
If you lose your API key or you suspect that your API key is compromised, you need to regenerate your API key, since you cannot recover it from the Airwallex web app. Regenerating will overwrite your old API key, and you will no longer be able to connect to the Airwallex API using your old API key. Your Client ID will remain the same.
Use these steps to regenerate your admin API key for your Airwallex account.
- Open Airwallex web app > Developer > API keys page.
- Click the three dots (…) next to your admin API key, and select Regenerate API key.
- Enter your login password.
- Copy the API key and keep it in a secure place as you won't be able to view it on the web app again.
Restricted API keys
Restricted API keys only grant limited access to Airwallex APIs for enhanced security. You can specify which Airwallex APIs each restricted API key can access. Use restricted API keys to reduce risk when using or building microservices. For example, you can use restricted API keys to integrate with Online Payments shopping platform plugins.
You can create multiple restricted API keys per account.
Create a restricted API key
Use these steps to create restricted API keys for your Airwallex account.
- Open Airwallex web app > Developer > API keys page.
- Click Create restricted API key.
- Enter a name for the restricted key in Name.
- Specify the scope, i.e, the resources accessible to the API key in Access. You can provide Edit or View permissions.
- Copy the API key and keep it in a secure place as you won't be able to view it on the web app again.
Note that scopes are aligned with the resource names in Airwallex APIs API. Scopes with View permissions provide access to GET endpoints, whereas Edit permissions provide access to both GET and POST endpoints. The use of restricted API keys is limited to certain APIs; however, if you require access to other APIs, please use the admin API key.
Regenerate a restricted API key
Similar to the admin API key, you can regenerate restricted API keys if you've lost the API key or suspect it has been compromised. Regenerating will overwrite your old API key, and you will no longer be able to connect to the Airwallex API using your old API key. Your Client ID will remain the same.
Use these steps to regenerate your restricted API key for your Airwallex account.
- Open Airwallex web app > Developer > API keys page.
- Click the three dots (…) next to the restricted key, and select Regenerate API key.
- Enter your login password.
- Copy the API key and keep it in a secure place as you won't be able to view it on the web app again.
In addition to regenerating a restricted key, you can perform the following actions by clicking the three dots (…) next to the restricted key. All actions require you to enter your login password.
- Edit API key: Allows you to edit the scope of the restricted key - this will not change the API key secret.
- Duplicate API key: Allows you to duplicate an existing restricted key to create a new one with the same or similar scope.
- Delete API key: Allows you to delete a restricted key.
Secure your API keys
As API keys are used to authenticate and authorize actions on your Airwallex account, keeping them secure and private is crucial.
We recommend implementing the following best practices when handling Airwallex API keys:
- Apply the principle of least privilege when creating restricted API keys and only enable the minimal set of access required for that key’s specific use case.
- Use a password manager or privileged access management system to store, share, view and audit access to API keys.
- Avoid sending API keys over untrusted or general-purpose communication technologies such as email, SMS and instant-messenger applications where possible.
- If you believe an API key has been inappropriately handled or viewed, ensure the API key is regenerated. Be mindful of the impact of regenerating a API key that's already in use.
- Avoid adding API keys directly in files of code or version control systems. You can instead use environment variables, user input or APIs for password and secret management systems to retrieve Airwallex API keys and use them in code.
Notifications
You will receive email notifications for the following events:
- Admin API key
- Generate key for the first time
- Regenerate key
- Restricted API key
- Create key
- Regenerate key
- Duplicate an existing key
- Edit scope of an existing key
- Delete a key