API credentials for Balance Platform

Generate and configure credentials for API requests related to the Balance Platform

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 marketplace or sending funds to third-party bank accounts.
- Session authentication API: create and manage session tokens required for integrating Platform Experience components.
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.
- Session authentication API: create and manage session tokens required for integrating Onboarding components.

In your 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:

Manage API credentials role

Merchant admin role

You can configure API credentials for your Balance Platform on the company account level only.

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 Customer Area.

When switching to your live environment, you must create a new API credential in your live 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 Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Platforms tab.
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 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 Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Platforms tab.
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 Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Platforms tab.
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 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 Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Platforms tab.
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 Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Platforms tab.
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.