To make requests to Adyen's APIs, you must have the appropriate API credentials. When your balance platform account is set up, it includes:
- An API credential for web services. This credential has a username in the following format: ws[_123456]@BalancePlatform.[YourBalancePlatform]. You can use this credential to authenticate requests to the following APIs:
- Configuration API: create and manage resources in your balance platform, including account holders, balance accounts, and business accounts.
- Transfers API: perform and manage transfers in your balance platform, such as moving funds within your or sending funds to third-party bank accounts.
- An API credential for legal entity management. This credential has a username in the following format: ws[_123456]@Scope.Company_[YourCompanyAccount]. You can use this credential to authenticate requests to the following API:
- Legal Entity Management API: onboard and manage legal entities and their verification information.
In your Balance Platform Customer Area, you can:
- Create API credentials
- Generate an API key for your credential.
- Enable the required API permissions for your credential.
This page explains how to create and configure your API credentials for web service and legal entity management (LEM) users.
Requirements
Make sure that your user account has one of the following roles:
- BalancePlatform Merchant Admin role
Create an API credential
You can have multiple API credentials linked to your Balance Platform, and activate or deactivate those credentials at any moment. Before creating credentials, consider that having fewer credentials minimizes the number of API keys you must handle, making your operations easier. However, having more credentials provides better control over API permissions, increasing security. Some sample use cases are:
- To separate web service users according to the permissions they have. For example, separating users that can create and configure accounts from users that can configure transfers.
- To isolate a web service user that has access to important permissions, such as PIN reveal or payment instrument reveal.
The following tabs explain how to create API credentials for both web service and LEM users in your Balance Platform Customer Area.
When switching to your live environment, you must create a new API credential in your live Balance Platform Customer Area.
The following sections explain how to configure your API credential.
Generate an API key
Use API keys to authenticate your requests. Every web service and LEM user has its own API key.
To generate an API key for a user:
- Log in to your Balance Platform Customer Area.
- Go to Developers > API credentials.
- Select the credential username.
- On the Configure API credential page, in the Server settings section, select API key.
- Select Generate API key.
- Select the copy icon and store your API key securely in your system.
You cannot copy the API key again after you leave the page.
- Select Save changes.
When switching to your live environment, you must generate a new API key in your live Balance Platform Customer Area.
Change an API key
You can change an API key when needed, for example, when an API key is lost or compromised. To do this, follow the steps to generate an API key.
When you generate a new API key, it can be used immediately. However, the previous key also remains active for the following 24 hours.
Extend the time of a previous API key
To extend the time that a previous API key remains active:
- Log in to your Balance Platform Customer Area.
- Go to Developers > API credentials.
- Select the credential username.
- On the Configure API credential page, in the Server settings section, select API key.
- Under Expiring keys, see how much time is left until the previous key expires. You can either:
- Select the reset icon to reset the expiry time to 24 hours.
- Select the expire now icon to expire the previous key immediately.
- Select Save changes.
Generate a basic authentication password
Users can also use basic authentication for API requests. To generate a basic authentication password:
- Log in to your Balance Platform Customer Area.
- Go to Developers > API credentials.
- Select the credential username.
- On the Configure API credential page, in the Server settings section, select Basic auth.
- Select Generate password.
- Select the copy icon and securely store your basic authentication password in your system.
You cannot copy the password again after you leave the page.
- Select Save changes.
When you generate a new basic authentication password, the previous password is deactivated immediately.
Instead of generating a new password for an existing API credential, you can create a new API credential. This enables you to use both your existing password and a new one until you have updated your systems.
When switching from your test to your live environment, use the basic authentication credentials from your live Balance Platform Customer Area.
Manage API permissions
Manage the permissions of a web service API credential by enabling or disabling its roles. An API credential must have at least one enabled role.
To do manage API permissions:
- Log in to your Balance Platform Customer Area.
- Go to Developers > API credentials.
- Select the username of the web service credential, for example: ws_[123456]@BalancePlatform.[YourBalancePlatform].
- On the Configure API credential page, under Permissions, expand the categories to see the lists of available roles.
You can also use the search bar to find specific roles. - Select the checkboxes of the roles you want to enable for the API credential.
- Select Save changes.
Deactivate an API credential
- Log in to your Balance Platform Customer Area.
- Go to Developers > API credentials.
- Select the credential username to open the Configure API credential page.
- Under General settings, turn off the toggle next to the Username to switch the status from Active to Inactive.
- Select Save changes.