A Service Account is often used for automation and system-to-system usage, such as the API user. When a user is set as a Service Account, that user will not be able to log on to the Engage application.
The Service Accounts overview shows all existing Service Accounts, in alphabetical order.
Each row contains the Service Account's name and last modification date.
The overview can be sorted by clicking on a column header.
The Search field at the top-right allows searching in the list of Service Accounts based on name.
From this overview you can:
- Create a new Service Account — See below.
- Delete an existing Service Account — By clicking on the bin icon at the end of a line.
- Edit an existing Service Account — By clicking on a name. The properties are then displayed in a right sliding panel.
Two tabs are visible when editing a Service Account:
- General — The General properties of the Service Account
- Endpoints — Operation rights to the different API endpoints. This tab is only visible for Custom Service Accounts. For integration specific Service Accounts (Recommendations and Site) the API endpoints are fixed and cannot be viewed or edited here.
Create a Service Account
To create a new Service Account, click on the New button
at the top-right.
The properties are then shown in a right sliding panel.
Enter the Service Account Name.
Select the type of Service Account:
- Custom: For example used by the Engage API.
- Recommendations: Used for the integration between Recommendations and Engage.
- Site: Used for the integration between Engage and Site. This information needs to be added in the Site universe configuration.
- Rendering: Used when activating the secure authorization requirement in Custom Journeys. Use the key and secret generated for this Service Account, to create the authorization header. (This is done by combining the key and secret with a colon and encoding the combined key as base64. These are your credentials that can be used for basic authorization.)
- Loyalty: Used for the integration between Loyalty and Engage.
- Luzmo: Used for the integration with Luzmo, the tool used for dashboard creation and management.
Save it.
Access Management - Service Accounts
An authentication key and secret key are automatically generated and can be used within the API.
An Expiration date can be set. The user can choose from a number of predefined values or define a custom expiration date. Once that is done, the expiration date is automatically calculated and added. When the expiration date has been reached or no expiration date is set, the user is informed.
Note: When the expiration date has been reached, the key and secret can be renewed directly from within the Service Account configuration panel. Click 'Renew' and a new key and secret are created. You can also set a new expiration date in which case the key and secret remain unchanged.
This means that a new key is generated and automatically becomes the current key. The old key remains valid for 2 weeks to provide API functionality to existing apps while they are being updated with the new key. After 2 weeks the old key becomes invalid.
If required, IP filtering can also be activated. This ensures that only calls from the given IP-adresses will be taken into account. If a call is made to the API from a different IP-adress, it won't work.
Optionally, you can also filter the organizations having access to this Service Account. As a result, API calls using this Service Account will only work for the organizations in the list. Toggle the option on and add the organizations. When the option is activated you need to select at least one organization.
Click Save.
Defining the Endpoints (Custom Service Accounts only)
The Endpoints tab provides and overview of all the API endpoints available and the different operations that are allowed on these endpoints.
Check the boxes to select the accessible endpoints and operations for the current Service Account.
Save when done.
Note: When no endpoints have been selected, the Service Account has no access at all.
Technical note: When a Service Account is not authorized to use an endpoint, the API will return a `403 - Forbidden` HTTP response code & message.
Access a Service Account to view API authentication keys
When accessing a Service Account, the properties are shown in a right sliding panel.
The Name is displayed.
An authentication key and secret key are displayed and can be used within the
API.
Access the API (Custom Service Accounts only)
The API can be accessed from a dedicated URL linked to your environment. (e.g. http://YOURENVIRONMENT/Portal/Api/swagger/)
When the API Explorer is launched, at the top right corner the key and secret need to be entered. You can now test the API methods.
Note: Documentation regarding the API and the use of the methods can be found directly in the API Explorer which is accessible from the Modules entry in the toolbar.
Or, you can also access the DevPortal for more detailed information on the API via the following URL: https://developers.meetmarigold.com/engage/api/ or from the Modules entry in the toolbar.
API Rate Limits
Rate limiting
A rate limit defines the number of requests that can be made to the Marigold Engage REST API within a given time period. If this limit is exceeded during a time window, the application will be throttled and API requests above the limit will be rejected.
Throttling is linked to the “Service Account” setup within Marigold Engage and applied to its related API key.
API Limits for Engage REST API
All Engage REST API requests are subject to rate limits. An API key is allowed to make up to 2500 requests per minute across all API paths.
Note: The API limits are only applicable to the Engage REST API. The Campaign and Direct Mail REST API are not subject to these limits.
Responses when requests are rate limited
If requests are being made at a rate higher than the limits of :
- 2500 requests / minute
then these requests will receive the HTTP status code 429 (Too Many Requests) with a message, like the example below, in the body of the response.
Example: API calls quota exceeded! The maximum allowed is 2500 per minute.
In the response headers additional information is presented about the rate limiting state.
Example:
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 5
- X-RateLimit-Limit — Represents the maximum number of allowed requests in the time window.
- X-RateLimit-Remaining — Represents the number of remaining requests in the current window (1 minute).
- X-RateLimit-Reset — Represents the time remaining in the current window expressed in seconds.
In the event that the Marigold Engage REST API is under high load or is down for maintenance, the HTTP status code 503 (Service Unavailable) will be returned.
API inbound request limit
Most API endpoints have inbound limitations set as following:
Default inbound request limit
- Limited by a 15 seconds connection time-out, meaning that the data should posted and processed within 15 seconds.
- Data size limited to 2MB.
- Default Rate limited to 2500 requests / minute.
The « POST /data/load » endpoints support higher inbound request limits, depending on the data transfer mode.
There are currently no quantity validation constraints on:
- the number of fields per record
- the total number of records returned
Note: the amount of fields & number of records is limited by the size of the total data object. Example: more fields mean less records that can be submitted and vice versa.
/data/load SYNC MODE
- Limited by a 15 seconds connection time-out, meaning that the data should be posted and processed within 15 seconds.
- Data size limited to 20MB.
- Number of data fields is not specifically limited.
- Number of records is depending on the number fields.
- Default Rate limited to 2500 requests / minute.
/data/load STREAMED MODE
- No connection time limit.
- Data limited is to 20MB.
- Number of data fields is not specifically limited.
- Number of records is depending on the number fields.
- Default Rate limited to 2500 requests / minute.
API Outbound response limits
The response limit is typically based on the total output of data & the time needed to retrieve the dataset, which is reflected by the number of fields defined. If the number of fields is low, the take can be higher.
Default outbound request limit
- Limited by a 15 seconds connection time-out, meaning that the data requested and returned within 15 seconds.
- Default Rate limited to 2500 requests / minute.
The « POST /data/search » endpoints support higher outbound response limits, depending on the data transfer mode.
There are currently no constraints on:
- number of export fields.
- number of records.
BUT the combination the amount of fields & number of records is limited by the size of the total data object.
/data/search SYNC MODE
- No time-out limit.
- Number of records is advised to limit to a "take" of "2500".
- Data limited to size of maximum 1MB per record.
- Default Rate limited to 2500 requests / minute.
/data/search STREAMED MODE
- No time-out limit.
- Data limited to size of maximum 1MB per record.
- Default Rate limited to 2500 requests / minute.
