API Consumers
  • 10 Sep 2020
  • 5 Minutes To Read
  • Print
  • Share
  • Dark
    Light

API Consumers

  • Print
  • Share
  • Dark
    Light

Early Access feature
If you would like to be an early adopter of this feature, please contact your Customer Success Manager (CSM) and request for API Consumers to be enabled on the environment of your choice. Your request should be processed in 2-6 weeks.

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.

Please be Aware
Once API Consumers is enabled on your environment, you will no longer be able to create new API Users using basic auth as we encourage the adoption of API Consumers. Request authentications will work both with Basic Auth (the Authorization header for old Mambu API users) and with API keys (apikey header for new mambu-api consumers) until further announcement.

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?

API Consumers feature

In order to use API Consumers, first make sure the feature is enabled on your environment by going to Administration and checking it has a green check box next to it, under 'Early Access Features.'

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.

API Consumers_Create

  1. 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.
Please be Aware
When you delete an API Consumer, all the API Keys for this consumer will be deleted as well.

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':

API Consumers_MambuAPI_Type

  1. Once you have created an API Consumer, you will see it appear in the API Consumers list.
  2. On the right hand side of the screen, click on Actions > Manage Keys.
  3. You will now see you can easily Generate one or more API Keys, according to your needs.
  4. To View and Copy an API Key, click Show. You can also Delete an API Key if you no longer need it.
Pay attention to the used authorization type & headers needed

When testing your API Access with your new API Key, please make sure you change the authorization type to "API Keys" and add the "apiKey" header with the value of your generated API Key.

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.

API Key Rotation is available with Mambu V9.53

If you already have API Consumers enabled on your environment, API Key Rotation will be available with Mambu V9.53. You can find the release notes here.

Instructions for use

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

  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.
    02 - API Key Rotation - Generate Secret Key

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

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

03 - API Key Rotation - Key Expiration

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

04 - API Keys with Expiration time

Please Note
When you call the api/apikey/rotation API endpoint with an expired or non-existent API key, a new API key will be generated.
Further development

At the moment, we do not support overlapping API keys. If you are interested in this feature or would like to send proposals for further development, please raise an idea using our idea portal.


Ask the Mambu Community

If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.

Ask a question about API Consumers

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

Was This Article Helpful?