API Keys

API keys are implemented in order to track and control the use of the API. Create the keys and assign permissions required for specific actions. They are essential when you integrate Synerise with other systems that you use in your daily work.

Permissions

Permissions allow you to define what kind of API methods are allowed when using an API key (the API methods are available at the link here). This allows users to create customized API keys for the needs of a particular integration. Such a structure provides you with safety when a key is stolen. As an additional form of protection, there is a possibility of defining IP addresses where the given API key can be used.

Allowlist and denylist

Allowlisting and denylisting in API keys allows you to configure which types of events can be sent to the event APIs when using that key. Events that manage promotions, transactions, loyalty points can be denylisted (or not included in the allowlist) for client-type API keys unless your business requires them to be allowed. Sensitive custom events used by your integration can be blocked too, to increase protection against fraud.

Prerequisites

• Plan the API key permission structure.
• Your account’s permissions must allow access to the API keys section.

Adding API keys

1. Go to Settings > API keys.
2. Click Add API key.
3. On the pop up:
   1. In the API key name, enter the name (it’s visible only on the list of API keys and allows identification of API key by the user).
   2. From the dropdown list, select the type of the key:
      • Profile - Keys in this section are used mostly in mobile applications when the Synerise RaaS (Registration-as-a-Service) is used (you can find more information about it here). They allow to register, log in, update some profile data and more.
      • Workspace - Keys in this section are used for operations that are related to workspace administration, integrations or batch processing.
   3. Optionally, write a description of the key to let other users know what it is for.

      

   Result: The new API key appears on the top of the list.
   

   

4. Define the settings of the API key by clicking icon and then selecting Edit.

   

General settings

In this section, you can get your API key and change its name and/or description.

Permissions

In this section, you can select the range of permissions for a single API key.

The permission matrix is divided into modules. To grant specific permissions within a module, select the checkbox. The name of the permission corresponds with the name of permissions required for the API method in the API documentation.

Allowlist

In this section, you can create a list of events which can be authenticated with the API key. All other events that are not on the list are rejected, even if permission and IP address settings allow for it.

The allowlist should only include events that are necessary for your integrations to work.

To add an event to the list:

1. Enter the name of the event in the text field.
2. From the dropdown list, you can select more events.
3. Confirm your choice by clicking Add.

Denylist

In this section, you can create a list of events which cannot be authenticated with the API key.

Denying events is a way of restricting sensitive actions and allowing performing only specific ones by an API key, which you can share with a group of selected co-workers in your organization. It can also serve as a way of protecting yourself from authenticating them if this API key (client type) is stolen.

To add an event to the list:

1. Enter the name of the event in the text field.
2. From the dropdown list, you can select more events.
3. Confirm your choice by clicking Add.

IP access restriction

This list allows you to define IP addresses from which requests with JWT generated with the API key will be accepted. This way, when an API key is stolen, and the fake requests are sent with JWT generated with the stolen key, they will be blocked because they are sent from a non-accepted IP address.

4. In the text field, enter an IP address.
5. Confirm by clicking Add address.
6. To add more addresses, repeat steps 1 and 2.