# API Consumers Source: https://docs.mambu.com/docs/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. :::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, Mambu Payments Gateway 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](/docs/api-consumers#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](/api/api-v2/consumers/consumers/) section of our API Reference. :::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**. :::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](#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](@site/static/img/support/View%20API%20consumers%281%29.png) ### 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](#api-consumer-access-settings-and-permissions). 4. Select **Save Api Consumer**. ![Create API consumer dialog](@site/static/img/support/Create%20API%20consumer%20part%201%281%29.png) ### 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](/docs/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](/docs/audit-trail)| | Streaming API | Manage Events Streaming (`MANAGE_EVENTS_STREAMING`) |[Streaming API](/docs/streaming-api) | | Mambu Payments Gateway API | Manage Payments (`MANAGE_PAYMENTS`) | [Getting Started - Payments](/docs/payments-settings)| ### 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](@site/static/img/support/developer--delete-api-consumer-confirmation.png) ## 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](#deleting-api-keys), or by [rotating them](#api-key-rotation) using secret keys. :::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](/docs/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](@site/static/img/support/Click%20Button%20Manage%20Keys.png) 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](@site/static/img/support/developer--generate-new-api-key.png) ### 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](@site/static/img/support/developer--manage-keys-dialog.png) ## 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](/docs/api-consumers#automatic-api-key-expiration-for-rotated-keys). :::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](/api/api-v2/apikey_rotation/rotate-key) 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](@site/static/img/support/developer--generate-secret-key-modal.png) ### 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. :::warning 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.](@site/static/img/support/developer--access-preferences-security-settings.png) ### 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. | 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 | 5 mintes after use | no | 1800 s | yes | | Secret Key | UI | 5 mintes after use | no | 1800 s | yes | | API Key | rotation | never | yes | 1800 s | yes | | Secret Key | rotation | 5 mintes after use | no | 1800 s | yes | ## 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](/docs/access-preferences#ip-access-restrictions) section of our Access Preferences article.