API Consumers
  • 08 Nov 2023
  • 11 Minutes To Read
  • Dark
    Light
  • PDF

API Consumers

  • Dark
    Light
  • PDF

Article Summary

Early Access Feature
If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

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.

Please Note

Basic authentication may only be used with the Mambu API. However, we recommend using API keys instead of basic authentication whenever possible - as it provides better flexibility and security.

Audit Trail, Payments API, and Streaming API do not support basic authentication. You must use API consumers and API keys to access these APIs.

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.

Please Be Aware

Your Mambu credentials are used to access and modify your account and information. It is important to securely store your credentials in order to prevent unauthorized access. We recommend storing your credentials in a password manager such as 1Password, or in another secure storage application.

Never send your credentials over unencrypted email or chat, post them to a help forum, or store them in a repository.

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

Some settings controlling API consumers may only be configured in the Mambu UI, and some default settings in the Mambu UI will override settings included in the body of requests, such as the API key expiration period for keys generated by rotation.

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.

Please Note

User access permissions are only required for calls to the API consumers endpoint when using basic authentication. Anyone with a valid API key may make any request to the API, regardless of their user permissions, as long as the key was generated by an API consumer with the appropriate permission. For more information, see API consumer access settings and permissions.

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.

API consumers list

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.

Create API consumer dialog

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.

CapabilityPermissionsLinks for more information
Audit TrailManage Audit Trail (MANAGE_AUDIT_TRAIL)Audit Trail
Streaming APIManage Events Streaming (MANAGE_EVENTS_STREAMING)Streaming API
Payments APIManage Payments (MANAGE_PAYMENTS)Getting Started - Payments

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.

Delete dialog for deleting an API consumer

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.

Please Note

For security and compliance reasons, when you clone your production data to sandbox, API keys are not copied over. You must create new API keys for your newly cloned sandbox environment. For more information on cloning production data to your sandbox environment, see Customer Service Portal - Cloning production to sandbox.

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.

Manage Keys option displayed in API consumer list

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.

Generate New API Key dialog

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.

Manage Keys Dialog

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.

Please Note

Do not include an API key or basic authentication headers when making calls to rotate keys, or you will receive an invalid credentials error. Use the secret key only when authenticating rotation requests.

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.

Generate Secret Key dialog with a secret key generated

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.

Please be Aware

The default grace period for key rotation is 1800 seconds, or 30 minutes. Note that if you do not change this value, then all rotated keys will remain valid for this amount of time.

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.

Access preferences with API Key Rotation Grace Period and Automatic Expiry of API consumer key fields available.

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.

KeyWhere createdDefault expirationCan override?Default grace periodCan override?
API KeyAPIneveryes1800 syes
API KeyUIneveryes1800 syes
Secret KeyAPI5 mintes after useno1800 syes
Secret KeyUI5 mintes after useno1800 syes
API Keyrotationneveryes1800 syes
Secret Keyrotation5 mintes after useno1800 syes

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.


Was this article helpful?

What's Next