API Consumers

API consumers are an abstraction similar to an OAuth client. The primary purpose of an API consumer is to generate API keys, which are used to authenticate API requests by including them in an apiKey header.

Mambu currently supports two methods for authenticating API requests:

• Basic authentication using user credentials, or
• API keys, which are unique UUID tokens provided in an apiKey header.

API consumers replace user accounts as the source of access credentials.

API keys inherit the scope of access permissions from the API consumer that creates them. For more information, see API consumer types below.

It is up to you to determine the right policy governing who has access to API consumers, how and when API keys are generated and expire, when to rotate keys, and so forth. Depending on how you configure your system, multiple users may be able to create and access one or many API consumers with different degrees of access, and each API consumer may generate multiple keys.

Once we have enabled API consumers for your account, you will no longer be able to add the API permission when creating a new user. However, you may edit any existing user to add the permission in Administration > Access > Users. Existing users with API access permissions may continue to use basic authentication.

Managing API consumers

API consumers are managed in two ways:

• Using the Mambu UI. We will cover this process in this article, along with providing a general introduction that will be useful for anyone using or managing API consumers.
• Via the API Consumers endpoint. For more information on creating, using, and managing API consumers via API v2, see the API Consumers section of our API Reference.

User permissions for managing API consumers

The following permissions are required for a user to be able to perform the relevant management actions on API consumers either via the UI or API:

• View Api Consumers and Keys (VIEW_API_CONSUMERS_AND_KEYS)
• Create Api Consumers and Keys (CREATE_API_CONSUMERS_AND_KEYS)
• Edit Api Consumers and Keys (EDIT_API_CONSUMERS_AND_KEYS)
• Delete Api Consumers and Keys (DELETE_API_CONSUMERS_AND_KEYS)

If these permissions are not assigned to a user, that user will not be able to see the API Consumers tab under Administration > Access.

Once we have enabled API consumers for you, an API Consumers tab will appear under Administration > Access.

You may generate and manage API consumers and keys in Administration > Access > API consumers.

You may configure relevant settings in Administration > Access > Preferences.

Creating API consumers

To create an API consumer in Mambu:

1. On the main menu, go to Administration > Access > API Consumers.
2. Select Add consumer.
3. Enter all the necessary information in the Create Api Consumer dialog. For more information about access settings and permissions fields, see API consumer access settings and permissions.
4. Select Save Api Consumer.

Deleting API consumers

If you delete an API consumer, any API keys and secret keys the consumer created will be deleted and immediately invalidated as well.

To delete an API consumer:

1. On the main menu, go to Administration > Access > API Consumers.
2. Find the API consumer in the list that you would like to delete and select Actions > Delete.
3. In the Delete dialog, select Delete.

API consumer types

When you create an API consumer, you must assign the consumer a type, which controls what actions the keys it creates may be used to authorize. The table below shows the avaialble API consumer types, what capabilities they can authorize, and what subset of permissions may be configured for the type.

API consumer access settings and permissions

Only the Mambu API and Payments API consumers have a subset of granular permissions that may be specifically configured. The other API consumer types generate keys that may be used to authorize all relevant supported actions for its specific capability.

Mambu API consumer permissions

You may assign optional roles, user types, or permissions to an API consumer with the Mambu API type.

The access settings apply to API consumers in the same way that they apply to users. For more information, see Understanding Users, Roles, and Permissions.

Payments API consumer permissions

There are eight required permissions for Payments API consumers. These permissions are assigned by default and cannot be edited when creating an API consumer via the Mambu UI. When creating an API consumer via API, you must assign these permissions explicitly.

The eight required permissions are:

API keys

The primary purpose of an API consumer is to generate API keys, which are used to authenticate API requests by including them in an apiKey header. API keys inherit the access permission scope from the API consumer that was used to create them.

One API consumer may generate multiple API keys, and they may be used concurrently.

You may optionally set an expiration time for any API key that you create. If you set an expiration time for your API key, the remaining lifetime of the key will be displayed next to the API key in the Manage Keys dialog in the Mambu UI.

You may invalidate API keys by deleting them in the Mambu UI or API, or by rotating them using secret keys as described below.

Generating API keys

To generate an API key:

1. On the main menu, go to Administration > Access > API Consumers.
2. Find the API consumer in the list that you would like to make an API key for, select Actions > Manage keys.
3. In the Manage Keys dialog, select Generate.
4. In the Generate New API Key dialog, you can optionally choose whether you want to enter an expiration time to live (TTL) in seconds.
5. Select Generate to finish generating the key.

Deleting API keys

When you delete an API key from the Mambu UI, it is immediately invalidated. Note that the grace period for key rotation does not apply when keys are deleted.

To delete an API key:

1. On the main menu, go to Administration > Access > API Consumers.
2. Find the API consumer in the list that you would like to make an API key for, select Actions > Manage keys.
3. Find the API key you want to delete in the list and select Delete.
4. In the Delete dialog, select Delete.

API key rotation

API key rotation allows you to invalidate specific API keys using a secret key for authentication. When a key is rotated, you will immediately receive a replacement API key and a new secret key in the response body.

You may specify the expiration TTL for the replacement key in the rotation request. If you do not provide an expiration value, and no automatic expiration time is specified in the UI, then the replacement key will never expire. We generally recommend always setting an expiration value for better security.

Note that if an automatic expiration time is configured in Automatic Expiry of API consumer key in the Mambu UI, that value will overwrite any expiration value you provide with your API call. For more information, see Automatic API key expiration for rotated keys above.

For more information about the API key rotation endpoint, see the API Key Rotation section of our API Reference.

Secret keys

Secret keys are generated by API consumers, and are used to authenticate API key rotation requests. They cannot be used to validate any other request.

Secret keys expire immediately upon use, unless a grace period is configured for key rotation, in which case they remain valid for that length of time after being used. Secret keys otherwise never expire.

You may only have one active secret key per consumer at any one time. The key may not be invalidated, but it may be regenerated through the Mambu UI, which will invalidate any existing key.

To generate a secret key in the Mambu UI:

1. On the main menu, go to Administration > Access > API Consumers.
2. Find the API consumer in the list that has the API key that you want to rotate and select Actions > Manage keys.
3. Select Generate Secret Key.
4. In the Generate Secret Key dialog, select Generate.
5. Copy the secret key and select Close.

Key rotation grace period

You may configure a grace period for key rotation in the Mambu UI. After a key is rotated, it will still be valid for the length of time specified by the grace period. The grace period applies to both API keys and secret keys.

To set the key rotation grace period:

1. On the main menu, go to Administration > Access > Preferences.
2. Under API Key Rotation Grace Period, enter the amount of seconds you want the grace period to last.
3. Select Save Changes.

Automatic API key expiration for rotated keys

You may configure an expiration value for all API keys generated during key rotation by setting an Automatic Expiry of API Consumer Keys value in the Mambu UI. This value will not affect keys created by the UI, or created using the createApiKeyByConsumer endpoint.

If you set this value, it will override any specified value for key expiration when new keys are generated by key rotation through the API.

If no value is provided in the Automatic Expiry of API Consumer Keys field of the Mambu UI, then rotated API keys will never expire by default.

To set the Automatic Expiry of API Consumer Keys value for keys generated by key rotation:

1. On the main menu, go to Administration > Access > Preferences.
2. Select the Automatic Expiry of API Consumer Keys checkbox.
3. Enter the TTL for the key in seconds.
4. Select Save Changes.

Key lifecycle

The table below summarizes our key lifecycle policy.

IP Access Restrictions

Mambu automatically blacklists any IP address that issues 10 consecutive calls from an API consumer using invalid credentials. The addresses will be blocked regardless of how much time elapses between calls, but a successful call will restart the count.

For more information on IP blocking and instructions on how to clear an address from being blocked, see the IP Access Restrictions section of our Access Preferences article.