API Consumers
- 27 Dec 2022
- 11 Minutes To Read
-
Print
-
DarkLight
-
PDF
API Consumers
- Updated On 27 Dec 2022
- 11 Minutes To Read
-
Print
-
DarkLight
-
PDF
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
apiKeyheader.
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.
Creating API consumers
To create an API consumer in the Mambu UI:
- On the main menu, go to Administration > Access > API Consumers.
- Select Add consumer.
- 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.
- 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.
| Capability | Permissions | Links for more information |
|---|---|---|
| Audit Trail | Manage Audit Trail (MANAGE_AUDIT_TRAIL) |
Audit Trail |
| Streaming API | Manage Events Streaming (MANAGE_EVENTS_STREAMING) |
Streaming API |
| Payments API | Manage Payments (MANAGE_PAYMENTS) |
Getting Started - Payments |
Deprecation Warning
Mambu used to manage access to different capabilities with API consumer types.
This approach has been replaced by the relevant permissions mentioned in API consumer access settings and permissions. The API consumer type feature via the API will phased out in the near future. Please transition to the new approach as soon as possible.
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.
Please be Aware
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:
- On the main menu, go to Administration > Access > API Consumers.
- Find the API consumer in the list that you would like to delete and select Actions > Delete.
- 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.
Please Note
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.
Please be Aware
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:
- On the main menu, go to Administration > Access > API Consumers.
- Find the API consumer in the list that you would like to make an API key for, select Actions > Manage keys.
- In the Manage Keys dialog, select Generate.
- In the Generate New API Key dialog, you can optionally choose whether you want to enter an expiration time to live (TTL) in seconds.
- Select Generate to finish generating the key.
- Store your API key in a secure location.
Deprecation Warning
Mambu used to allow you to view API keys in clear text by using the Mambu UI or API v2.
In the Mambu UI, you are no longer able to view API keys in clear text after generation for security reasons.
Mambu API v2 will temporarily provide two endpoints for retrieving API keys. You may use the new /api/consumers/{consumerId}/keys endpoint, to retrieve an API key ID and a 6 character clear text prefix of the API key.
You may also use the old /consumers/{apiConsumerId}/apikeys endpoint, to retrieve API keys in clear text. However, support for this endpoint will terminate at the end of January 2023.
For more information, see API Consumers in our API v2 Reference.
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:
- On the main menu, go to Administration > Access > API Consumers.
- Find the API consumer in the list that you would like to make an API key for, select Actions > Manage keys.
- Find the API key you want to delete in the list and select Delete.
- 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.
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.
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:
- On the main menu, go to Administration > Access > API Consumers.
- Find the API consumer in the list that has the API key that you want to rotate and select Actions > Manage keys.
- Select Generate Secret Key.
- In the Generate Secret Key dialog, select Generate.
- 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.
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:
- On the main menu, go to Administration > Access > Preferences.
- Under API Key Rotation Grace Period, enter the amount of seconds you want the grace period to last.
- 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:
- On the main menu, go to Administration > Access > Preferences.
- Select the Automatic Expiry of API Consumer Keys checkbox.
- Enter the TTL for the key in seconds.
- Select Save Changes.
Key lifecycle
The table summarizes our key lifecycle policy.
| Key | Where created | Default expiration | Can override? | Default grace period | Can override? |
|---|---|---|---|---|---|
| API Key | API | never | yes | 1800 s | yes |
| API Key | UI | never | yes | 1800 s | yes |
| Secret Key | API | immediately upon use | no | 1800 s | yes |
| Secret Key | UI | immediately upon use | no | 1800 s | yes |
| API Key | rotation | never | yes | 1800 s | yes |
| Secret Key | rotation | immediately upon use | no | 1800 s | yes |
IP Access Restrictions
Mambu automatically blocks any IP address that issues a total of 10 requests to the Mambu API from an API consumer using invalid credentials. 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?
