API Tokens are used to authenticate and authorize all API requests to Interaction Studio's REST API. This REST API provides access to read and update data at several levels:
- Create and update users and accounts within Interaction Studio
- Receive behavioral data from offline systems
- Receive historical transaction data
- Create and update catalog data, including products and content
Create an API Token
The Interaction Studio REST API utilizes API tokens to authorize all data changes.
- Log into Interaction Studio as an Administrator
- Navigate to Security -> API Tokens
- Click Create Token
- Permissions are set by default and should not be changed
- Can access API - not selected
- Can send events - selected
- (Optional) If you want to restrict access to specific datasets in your account, add them in Restrict to Specific Datasets, otherwise the token will apply to all current and future datasets in your account
- (Optional) Add any Notes about the token as needed
- (Optional) Define an IP Accept List of addresses may use this token. If configured, requests originating from addresses not on the accept list will be rejected
- Click OK
- Once created, a dialog will appear where you can access the API Key ID and API Key Secret, which function like a username and password in an API request. Since these values can be used to access your data in Interaction Studio, they should be downloaded and stored securely. Once you close this dialog, you will be unable to access these values again.
Use an API Token in an API Request
When making an API request, you must set the HTTP Authorization Header using Basic encoding:
- Most REST clients provide the option to set Basic credentials using a username / password. In this situation, supply the API Key ID as the username, and the API Secret Key as the password.
- If you must construct the HTTP authorization header value manually, use Basic encoding as shown below:
Where <encoded-credential> is a strict Base64 encoding of
Replace a Legacy API Token in API Request
Legacy tokens are no longer supported and will stop working on June 1, 2020.
When making an API request add a query string parameter called _at to the API URL. Attempting to use this parameter with a new API token will generate an error.
Migrating Legacy API Tokens to New API Tokens
- Determine if you are using any legacy API tokens (a token created prior to March 7, 2020)
- You can use the token's Key Age to determine if it is a legacy token
- If you need help determining if any of your API tokens are legacy tokens, please contact support
- Create new tokens to replace your legacy tokens using the procedure outlined above
- Replace API calls in your application(s) with the new calling method described above
- The new token key ID and secret must be supplied in the HTTP Authorization header
- Attempting to use the legacy _at query string parameter with a new token will produce an error