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 individual 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 settings from the API consumer that creates them. For more information, see API consumer access settings and permissions.

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 the Mambu UI:

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.

API consumer access settings and permissions

When you create an API consumer, you must assign the relevant access settings. The API keys that the API consumer creates, will then inherit the access settings scope.

The access settings determine which capabilities an API key may access and which actions it may authorize. They may be assigned either by assigning permissions directly to the API consumer, by assigning a role, or assigning a user type. For more information, see Understanding Users, Roles, and Permissions.

The table shows some of the available capabilities Mambu offers and which permissions an API consumer must have to access them.

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.

You cannot delete an API consumer after any of its keys has been used. The API consumer will have an activity logged, and it must be maintained for audit trail purposes.

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 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 settings 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.

• Because API keys are used to authenticate access to your account, we recommend setting an expiration length for them, rather than creating keys that do not expire.

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

Generating API keys

When you generate an API key, it will be presented in clear text only once. After this, you may view the API key ID and a six character clear text prefix of the API key.

Since you are not able to retrieve an API key in clear text after generation, you must store your API key in a secure location upon generation.

Also, the six character API key prefix is not guaranteed to be unique. Therefore, you must base any identification process on the API key ID.

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.
6. Store your API key in a secure location.

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

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.

Unless a grace period is configured for key rotation, secret keys expire in 5 minutes, as this is our minimum TTL used in caching for performance purposes. 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 in 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 summarizes our key lifecycle policy.

Blocking IP Adresses

Mambu automatically blocks any IP address that issues a total of 10 requests from an API consumer using invalid credentials. This applies even if the IP has been whitelisted. The addresses will be blocked regardless of how much time elapses between calls.

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.