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.
    The scope of options to configure depends on the type of the API key (whether it’s Profile or Workspace).

    Profile API key
    Profile API key

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.

Basic access authentication

This option is only available for workspace API keys.

It allows you to simplify API integrations, but requires additional security measures compared to JWT. For more details, see “Basic API authentication with API keys” in “Workspace authorization”.

If you need to enable basic access authentication:

  1. Switch the Enable basic access authentication option on.
  2. On the confirmation pop-up that appears, click Apply.
    Result:
    Basic authentication is enabled. You can copy the workspace’s GUID (used as the login part of the authentication) from the settings:
Basic authentication enabled, the workspace GUID is shown
Basic authentication enabled, the workspace GUID is shown

You can now use basic authentication in API endpoints that are available to workspaces.

Simple authentication

This option is available only for profile API keys.

Simple authentication is a method available in Mobile SDK and it authenticates customers based on email address or custom ID.

In this section on the interface, you can generate a salt by enabling the Simple authentication toggle which is required in the integration process for the simple authentication method in Mobile SDK. The salt will be available in the Salt field and it must be added to the initialization script and kept encrypted in the code.

Note: The complete instruction on implementing simple authentication in mobile SDK is available here.

Profile modification allowlist

This option is available only for profile API keys.

Profile modification allowlist is an option that lets you specify which profile attributes and tags can be changed when using a specific API key for authentication and updating profiles. This helps you control and limit the scope of modifications that can be made using that API key. For example, the request for changing the first name and address will be rejected (403 error will be returned in response) if these attributes aren’t selected in the profile modification allowlist.

To be able to choose from any attributes and/or tags, you must either create them in Data Management > Params Manager and Data Management > Profile Tags respectively or send them through API.

Important:

If you use simple authentication, the attribute allowlist must include:

  • UUID
  • email or customId (depending on the identifier you will use in this method)
😕

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