A general overview of the elements that play a role in the Engagement API Authentication
There are several components that play a role in authentication in Bloomreach Engagement.
Firstly, in each call you make, you have to specify a base URL. This is the URL of the instance that you are using. This can be, for example, simply https://api.exponea.com/, but in many cases, this would be your own custom URL.
Secondly, each project under that instance will have its own distinct identifier called project token. This is a code containing numbers and alphabetical characters that identify that specific project. You will need to specify the project token in every API call you make as well.
Both of these can be found in Project settings > Access management > API.
Lastly, you will need to generate accesses with specific permissions that you will need to specify in the authorization section of the header in each API call that you make. This is where our API Groups come into place. These can be configured at the same location as mentioned above.
API Groups
API Groups are collections of API access keys. Each group can contain several different keys, and every group can have a different set of permissions allowing access to data in Bloomreach Engagement through API. This means that you can configure these permissions within each group individually. This allows you to create different groups for different use cases and stay compliant with the access minimization principle.
To learn how to create new groups, configure the group permissions, and set up accesses, follow our Get Started guide.
Each group can use one of the two available access types in Bloomreach Engagement - a public and a private access type. You can configure this when creating a new group.
Public API Access
The Public API Access can only be used with some of the API methods, predominantly for front-end access. This type of access is mostly used with our SDKs or tracking, and should not be used for private data manipulation.
To use the Public API Access, you will need to generate an API Token. The API Token is used in the authorization header.
Private API Access
The Private API Access can be used with all of our methods and is suitable for the manipulation of sensitive data.
To use the Private API Access, you will need to generate an API Key ID and an API Secret. In every API request that requires Private API Access, you have to include an authorization header consisting of an API Key/API Secret pair.
The purpose of the API Secret here is that it adds a new layer of protection to the most sensitive data. Keep in mind that only a handful of people or systems should have access to it.
To support even higher security, we also give the ability to rotate the API Secret. We recommend rotating keys regularly, depending on your security requirements. You can also revoke the API Secret anytime. Both of these actions can be done within the Bloomreach Engagement interface as well as programmatically, using our Revoke API Secret and Rotate API Secret calls.
Using the API Groups
Let’s look at the following example: You want your end-user to be able to log in to their account on your website or customer portal, navigate to their profile, and view all their consents or change them. You wish these consents to be stored in Bloomreach Engagement as well.
To achieve this and to follow the access minimization principle, you can set up a new API group for this specific use case: consent manipulation. Because consents are considered sensitive and private data, our GDPR API calls require you to set up the Private (access) Group.
After creating a new group, you will be able to set up the relevant permissions. Remember to only allow those permissions that are relevant to the use case that you are using the API group for.
In this case, that would only be:
Events
- Consent: Get + Set
