API credentials for web services

To perform requests to the Configuration API and Transfers API, you must have an API credential for a web service user.

When your account is set up, it includes one API credential for web services. However, you can create new API credentials if required.

To use your existing API credentials, you must:

• Generate an API key or basic authentication username and password.
• Enable the required API permissions for your credential.

This page explains how to create and configure your web service API credentials for the Configuration API and Transfers API.

Create an API credential

Create an API credential for a web service user to make requests to Configuration API and Transfers API. You can create multiple API credentials to increase the security of your platform.

To create an API credential, you must have the following role:

• Merchant Admin user role

To create an API credential for a web service user:

1. Log in to your Balance Platform Customer Area.
2. Go to API credentials.
3. Select Create new credential.
   The Create API credential window appears.
4. Under Credential type, select Web service user.
5. In the Description field, you can describe the purpose of the credential. This is optional.
6. Select Create credential.
   The configuration page for your new credential is opened.

Your new API credential has a username with the following format: ws_[123456]@BalancePlatform.[YourBalancePlatform].

The following sections explain how to configure your API credential.

Generate an API key

Generate an API key to authenticate your request. To generate an API key, you must have the following role:

• Merchant Admin user role

To generate your API key:

1. Log in to your Balance Platform Customer Area.
2. Go to API credentials.
   This opens a list of API credentials linked to your company account.
3. Select an existing API credential username, for example ws_[123456]@BalancePlatform.[YourBalancePlatform].
4. Under Server settings > Authentication, select the API key tab.
5. Select Generate API key.
6. Select the copy icon and store your API key securely in your system.
7. Select Save changes.

Change your API key

You can change your API key when needed, for example, when your 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 you can use the old API key

To extend the time you can use the old API key:

1. Log in to your Balance Platform Customer Area.
2. Go to API credentials.
   This opens a list with API credentials linked to your company account.
3. Select an existing API credential username, for example ws_[123456]@BalancePlatform.[YourBalancePlatform].
4. Under Server settings > Authentication select the API key tab.
5. Under Expiring keys, see how much time is left until the previous key expires. You can:
   • Select the reset icon to reset the expiry time to 24 hours.
   • Select the expire now icon to expire the previous key immediately.
6. Select Save changes.

Generate a basic authentication password

If you're using basic authentication to authenticate your API requests, you can generate a basic authentication password:

1. Log in to your Balance Platform Customer Area.
2. Go to API credentials.
   This opens a list with API credentials linked to your company account.
3. Select the credential username you want to generate the password for.
4. Under Server settings > Authentication, select the Basic auth tab.
5. Select Generate password.
6. Select the copy icon and store your basic authentication password securely in your system.
7. Select Save changes.

Instead of generating a new password, you can create an API credential. This enables you to use both your existing password and a new one until you have updated your systems.

Manage API permissions

Manage the permissions of an API credential by assigning them roles.

To edit the roles of an API credential:

1. Log in to your Balance Platform Customer Area.
2. Go to API credentials.
   This opens a list with API credentials linked to your company account.
3. Select an existing API credential username, for example ws_[123456]@BalancePlatform.[YourBalancePlatform].
4. Under Permissions > Roles, expand the category accordions to see lists of available roles. Use the search bar to filter the lists of roles.
5. In the lists, select the roles you want to enable for the API credential.
6. Under Accounts, select the accounts the credential can access.
7. Select Save changes.

Multiple API credentials

When deciding whether to create multiple API credentials, consider that having fewer credentials minimizes the number of API keys you must handle. Alternatively, having more credentials provides better control over API permissions, increasing security. For example:

• 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 manage transfers.
• To isolate a web service user that has access to important permissions, such as PIN reveal or payment instrument reveal.

These are just some considerations. Ultimately, the number of API credentials you use is your decision.