API credentials

Generate and configure credentials for the API requests that you make to Adyen.

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. When your account is set up it includes one API credential. You can also create multiple API credentials to improve security and control access.

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 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 integration.
Customer Area roles	Make sure that your user account has one of the following roles: Manage API credentials role Merchant admin role

Multiple API credentials

When deciding whether to create multiple API credentials, consider the following trade-offs. Fewer credentials mean fewer API keys to manage, while more credentials provide finer control over permissions and can improve security. For example:

If you have both an online sales channel and a point-of-sale sales channel, we strongly recommend creating a separate API credential for each channel.
If you are doing unreferenced refunds for online payments, we strongly recommend creating a separate credential for processing these refunds.
If you have an ecommerce system and a shipping system, you can separate the permissions for initiating and capturing payments.

Some merchants also create separate API credentials for different legal entities or different websites. The number of API credentials you create ultimately depends on how you want to structure access and permissions in your integration.

Create additional API credentials

Your account includes default API credentials. You can create additional credentials to better manage your integration.

To create a new API credential:

Log in to your Customer Area and select your Company account.
Go to Developers > API credentials.
This opens a list with all API credentials linked to your company account.
Select the Payments or Platforms tab, depending on your integration type.
Select Create new credential.
In the Create API credential dialog, under Credential type, select Web service user.
Optional. In the Description field, describe the purpose of the credential.
Select Create credential.
On the Configure API credentials page, save the generated Username, for example, ws_123456@Company.[YourCompanyAccount].
Under Server settings > Authentication select the API key tab.
Select Generate API key.
Select the copy icon and store your API key securely in your system.
Select Save changes.

Generate an API key

Use API keys to authenticate your requests.

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 your API key:

Log in to your Customer Area and select your Company account.
Go to Developers > API credentials.
Select the Payments or Platforms tab, depending on your integration type.
Select the credential username.
Under Server settings > Authentication select the API key tab.
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 you switch to your live environment, you must generate a new API key in your live Customer Area.

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.
Go to Developers > API credentials.
A list appears with all API credentials linked to your company account.
Select the Payments or Platforms tab, depending on your integration type.
Select the credential username you want to generate the password for.
On the Configure API credential page, in the Server settings section, select Basic auth.
Select Generate password.
Select the copy icon and store your basic authentication password securely in your system.
Select Save changes.

When you switch to your live environment, use the basic authentication credentials from your live Customer Area.

Manage API permissions

Permissions for a 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 the Payments or Platforms tab, depending on your integration type.
Select the credential username.
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.

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 Payments or Platforms tab, depending on your integration type.
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.

Add an allowed IP range

As a security measure, you can add allowed IP addresses to your API credential. When you add an allowed IP range, only requests originating from that range will be permitted.

To add allowed IP addresses:

Log in to your Customer Area.
Go to Developers > API credentials.
Select the Payments or Platforms tab, depending on your integration type.
Select the credential username.
Under Server settings, select Allowed IP range.
Add IP addresses that you want to allow access from.
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.
Go to Developers > API credentials.
Select the Payments or Platforms tab, depending on your integration type.
Select the credential username.
Under General Settings use the toggle to switch the webservice user to Inactive.
Select Save changes.

This change takes effect immediately and prevents the processing of API requests with this credential. You can switch it back to Active at any time to allow API requests again.