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.

WARNING: Keep the API keys secret. A leaked key must be deactivated immediately!
Important: We highly recommend changing API keys every 3-6 months for improved security.

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.
      Adding a new API key
      Adding a new API key
    Result: The new API key appears on the top of the list.
    Adding a new API key
    A new API key on the list
  4. Define the settings of the API key by clicking Three dot icon icon and then selecting Edit.
    Adding a new API key
    API key settings

General settings


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

Adding a new API key
General settings section

Permissions


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

List of permissions
List of permissions

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.

Adding a new API key
Permissions 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.

List of events authenticated with the API key
List of events authenticated with the API key

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.

List of events that cannot be authenticated with the API key
List of events that cannot be authenticated with the API key

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


Important: This option is available only for the Client type of API keys.

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.

Blank IP access restriction section
Blank IP access restriction section
  1. In the text field, enter an IP address.
  2. Confirm by clicking Add address.
  3. To add more addresses, repeat steps 1 and 2.
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker