API Consumers

What is API Consumers?

API Consumers is a new feature whose end goal is to unify the authentication of Mambu API users, Mambu Apps and Mambu Capabilities using only API keys based authentication instead of basic authentication.

What does the API Consumers feature bring into the picture of Mambu Authentication?

1. Currently, API Consumers is the only accepted authentication method that will enable you to also request to try-out some of our new Mambu capabilities like Audit Trail, Payments and Streaming APIs. If you want to test these new capabilities, you will also need to be an early adopter of API Consumers.

2. At the same time, through the use of API Consumers with the specific 'mambu-api' consumer type, we offer access to our Mambu APIs through API Keys and we highly recommend using this authentication method instead of basic auth.

In a nutshell:

• This feature allows the creation of API Consumers of a specific type.
• For each consumer type, multiple API keys can be generated.
• Depending on the selected type (for instance for mambu-api consumers) you might have to give the consumer certain permissions in order to be able to perform the desired operations.
• After creating a consumer and generating a key, in order to authenticate the requests, the generated API key will be sent in the apikey header.

How do I create a new API Consumer?

If you have this feature enabled, to start using it, do the following:

1. From the main menu, navigate to Administration > Access > API Consumers.
2. Click on Add consumer.
3. Add a relevant Consumer Name.

4. Select a Consumer Type from the following:

   • Audit — for setting up authentication & authorization for the Audit Trail capability.

   • Streaming API — for setting up authentication & authorization for the Streaming APIs capability.

   • Payments — for setting up authentication & authorization for Payments Services capability. For this type, the predefined needed permissions will appear but will not be editable.

   • Mambu-API — this type will enable you to create API Consumers for any needed consumer of our “regular” APIs. We encourage using this type of API Consumer and Keys to transition any current basic auth API users you might have created.

To delete an API Consumer:

1. On the main menu, go to Administration > API Consumers.
2. Find the API Consumer you want to delete in the list and then, on the right hand side of the row, click on Actions > Delete.
3. Click on Delete again to confirm.

How do I use API Consumers & Keys for Mambu API access?

1. Create an API Consumer of type "mambu-api".

2. You can apply a predefined "User Type" like Administrator or apply granular permissions from the permissions lists.

3. Starting with Mambu V9.53, you can apply a specific User Role to a "mambu-api" Consumer. This role can either be specifically created for API usage or can be a role impacting both UI and API access. For API Consumers, only the Role permissions that are applicable for APIs will be applied.

   Here's how the Create/Edit API Consumer screen looks like with V9.53, where we introduced Roles applicability to API Consumers of type 'mambu-api':

4. Once you have created an API Consumer, you will see it appear in the API Consumers list.
5. On the right hand side of the screen, click on Actions > Manage Keys.
6. You will now see you can easily Generate one or more API Keys, according to your needs.
7. To View and Copy an API Key, click Show. You can also Delete an API Key if you no longer need it.

How do I rotate my API key?

To enhance API Consumers and API Keys, we are introducing API Key Rotation in order to add an additional level of security for authentication & authorization to Mambu APIs, Mambu Services, and Third Parties App integrations.

Instructions for use

1. On the Manage Keys screen of an API Consumer, click the Generate Secret Key button.
   

2. Once you click on Generate Secret Key, an obfuscated secret key will be displayed. You can directly "Copy" the key by using the respective button.

3. Optional: To generate a new key, click on Generate again.
   

4. Pass the secret key value through the secretkey header in order to rotate an api key via POST/apikey/rotation API 2.0 endpoint on behalf of an API consumer. To read more on how to use this endpoint, please see API Keys - Rotation Endpoint.

Request example

curl --location --request POST 'https://demotenant.mambu.com/api/apikey/rotation' --header 'secretkey: <secret_key_value>'
{
  apikey: <old_api_key_value>,
  expiration_time: <time_in_seconds>
}

Response example

{
  apikey: <new_api_key_value>,
  secretKey: <new_secret_key_value>
}

5. Optional: On the Manage Keys screen, when you click on Generate, set an expiration time for your API key with a value between [0, 100000000] seconds . If you don't want to set an expiration time for a key, leave the "seconds" field empty.

6. Once you set an expiration time, the key will expire after the set number of seconds. You can check the remaining time by refreshing the Manage Keys window.

* If you don't already have an account you will be prompted to create one when you first visit the site.