Iterable's API can be used to interact with a project's contacts, templates, campaigns, journeys and more. To authenticate with the API, use an API key.
This document describes the types of API keys Iterable provides, how to create them and how to use them.
Table of contents
Types of API keys
Iterable provides four different types of API keys, each of which can access a different subset of Iterable's API endpoints:
-
JavaScript
Useful for calling Iterable's API from front-end JavaScript code, this type of API key can access the following endpoints:
-
Mobile
Useful for calling Iterable's API from mobile apps (for example, when using Iterable's iOS SDK, Android SDK or React Native SDK) this type of API key can access the following endpoints:
POST /api/users/disableDevice
POST /api/users/registerDeviceToken
POST /api/users/update
POST /api/users/updateEmail
POST /api/users/updateSubscriptions
POST /api/commerce/trackPurchase
POST /api/commerce/updateCart
POST /api/events/trackPushOpen
POST /api/events/trackInAppOpen
POST /api/events/trackInAppClick
POST /api/events/trackInAppClose
POST /api/events/trackInAppDelivery
POST /api/events/inAppConsume
POST /api/events/track
GET /api/inApp/getMessages
If possible, when using a mobile API key, we recommend using JWT authentication for additional security.
-
Read-only
WARNING
Never embed read-only API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access project data. Use read-only API keys only when making API calls from your servers.
Useful for calling Iterable's API in situations where data should only be read (never modified), this type of API key can access the following endpoints:
GET /api/campaigns
GET /api/channels
GET /api/messageTypes
GET /api/lists
GET /api/users/getFields
GET /api/metadata
GET /api/campaigns/metrics
GET /api/experiments/metrics
GET /api/templates
GET /api/templates/email/get
GET /api/templates/push/get
GET /api/templates/sms/get
GET /api/templates/getByClientTemplateId
GET /api/templates/inapp/get
GET /api/lists/{listId}/size
GET /api/campaigns/recurring/{id}/childCampaigns
GET /api/metadata/{table}
GET /api/metadata/{table}/{key}
-
Server-side
WARNING
Never embed server-side API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access all of your project's data. Use server-side API keys only when making API calls from your servers.
Server-side API keys can access all of Iterable's API endpoints, except for:
POST /api/events/trackWebPushClick
POST /api/users/registerBrowserToken
POST /api/users/disableDevice
POST /api/users/registerDeviceToken
POST /api/events/trackPushOpen
POST /api/events/trackInAppOpen
POST /api/events/trackInAppClick
POST /api/events/trackInAppClose
POST /api/events/trackInAppDelivery
POST /api/events/inAppConsume
Creating API keys
To create API keys for an Iterable project:
Sign in to an Iterable project as an org admin or as a member that has the Project Configuration > Data Feeds, Third-Party Integrations, API Keys and Webhooks permission.
Navigate to Integrations > API Keys. This screen lists information about each of the API keys that have been created for the project, but it does not display the full API keys.
Click New API Key.
-
In the Create a New API Key window, enter a name for the key and select the type of API key you'd like to create. Then, click Create.
To use JWT authentication with a mobile API key, check Require JWT Authentication on the bottom of the window. Every call to Iterable's API that authenticates with a JWT-enabled API key must also include a valid JWT as the value of an
Authorization
header (Bearer schema). For more information, read JWT-Enabled API Keys.WARNING
If you enable JWT authentication for an API key, you cannot later convert it to a different type of API key. For example, you cannot change a mobile API key that requires JWT authentication into a server-side API key.
-
In the Copy Your New API Key window, copy the API key:
If your API key requires JWT authentication, also copy the JWT Secret your server should use when generating per-user JSON Web Tokens:
Store the values displayed on this screen in a secure location. After you close the window, Iterable cannot display them again. If you lose them, you'll need to create a new API key.
Editing API keys
To change the type or name of an API key:
Navigate to Integrations > API Keys.
Click Edit for the API key you'd like to modify.
-
In Edit API Key window, provide updated values for an API key. Then, click Update.
TIP
You cannot change the type of an API key that requires JWT authentication.
Deleting API keys
To delete an API key:
Navigate to Integrations > API Keys:
Find the API key to delete. In its row, click the down arrow and select Delete Key.
Confirm the deletion.
Using API keys
IMPORTANT
All calls to Iterable's API should support TLS 1.2. Starting October 22, 2021, API calls that do not support TLS 1.2 will fail. For more information, see our release notes from September 22, 2021.
There are various ways to use Iterable API keys:
From Iterable's API docs. Paste the API key in the Authentication Header input (in the upper-left corner of the screen) and click Apply. Then, make API calls as necessary directly from the API docs.
-
With a third-party tool such as Postman, Insomnia or curl. Use the API key as the value for an
Api_Key
orApi-Key
request header. For example:curl -H "Api_Key: 7edf98199a5b49fa8bd016622432632a" https://api.iterable.com/api/users/docs@iterable.com
With Iterable's JavaScript SDK, iOS SDK, Android SDK or React Native SDK.
Comments
0 comments
Article is closed for comments.