To securely authenticate your requests to Adyen's APIs, you need API credentials. These act as the identity for your integration, and ensures that every request is authorized and linked to the correct account.
An API credential consists of:
- Username: An identifier in the format
ws_123456@Company.[YourCompanyAccount]. - API key: A password to authenticate API requests.
- Roles: Permissions that define what the credential is allowed to do.
API credentials are created automatically during your balance platform setup. You can manage them within your Customer Area. From there, you can:
- Create additional API credentials
- Generate an API key
- Configure API permissions by assigning specific roles to your credentials
Requirements
Before you begin, take into account the following requirements.
| Requirement | Description |
|---|---|
| Integration type | An Adyen for Platforms integration. |
| Customer Area roles | Make sure that your user account has one of the following roles:
|
API credentials included with your balance platform
When your balance platform account is set up, it includes API credentials that represent API users in your Customer Area. Your integration uses one or both of the following user types:
- Web service users: Used to authenticate requests to Adyen APIs.
- LEM users: Used to authenticate requests to the Legal Entity Management (LEM) API.
| User type | Username format | Authenticates requests to |
|---|---|---|
| Web service | ws[_123456]@BalancePlatform.[YourBalancePlatform] |
• Configuration API: Manage account holders and balance accounts. • Transfers API: Process transfers and Adyen-issued card payments. • Session authentication API: Create session tokens for Platform Experience components. • Capital API: Offer business financing (additional configuration required). |
| Legal entity management | ws[_123456]@Scope.Company_[YourCompanyAccount] |
• Legal Entity Management API: Onboard and manage legal entities and verification information. • Session authentication API: Create session tokens for Onboarding components. |
Create additional API credentials
Your balance platform account includes default API credentials. You can create additional credentials to better manage your integration.
Using fewer credentials simplifies operations because you have fewer API keys to manage and rotate. Creating additional credentials, however, allows you to apply more granular API permissions and improve security. If an API key is compromised, its access is limited to the specific permissions assigned to that credential.
Common use cases to create additional API credentials include:
- Granular access control: You want to separate credentials based on their function. For example, use one credential to manage account holders and another to process transfers.
- Sensitive data isolation: You want to create dedicated credentials for actions such as PIN reveal or payment instrument reveal so these permissions are not bundled with standard API operations.
The following tabs explain how to create API credentials for both web service and LEM users.
When switching to your live environment, you must create new API credentials in your live Customer Area.
Generate an API key
Use API keys to authenticate your requests. Every web service and LEM user has its own API key.
You can generate a new API key at any time, for example if a key is lost or compromised. When you generate a new API key, it becomes active immediately. The previous key remains active for 24 hours to allow you to update your systems.
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.
Reset the expiry time of a previous API key
You can reset the expiry time of a previous API key by following these steps:
- 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, and then 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
If you are using basic authentication to authenticate your API requests, you can generate a basic authentication password for your API credential.
When you generate a new basic authentication password, the previous password is deactivated immediately.
If you want to continue using your existing password while updating your systems, you can instead create a new API credential. This allows both credentials to remain active until you have updated your systems.
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 switching from your test to your live environment, use the basic authentication credentials from your live Customer Area.
Manage API permissions
Permissions for a web service API credential are defined by its enabled roles. An API credential must have at least one enabled role.
To manage API permissions:
- Log in to your Customer Area and select your Company account.
- Go to Developers > API credentials.
- Select either the Payments tab or 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
API credentials cannot be deleted. However, you can deactivate a credential to prevent its API keys from being used. To 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.