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 guide describes the types of API keys Iterable provides, how to create them, and how to use them.
In this article
API key security
API keys are secrets that open a gateway to read and/or update the data contained in your Iterable project. Before you make an API key, it's imperative to consider the level of security necessary and decide on the correct API key type and JWT authentication (client-side only).
When you decide which API key to create, consider:
- Where the API key will be used (server-side applications vs client-side applications)
- What actions the API key will perform (read only, update)
- What data and endpoints the API key will interact with
- Who will have access to the key (client-side keys are accessible to malicious users, while server-side keys are kept secret)
Server-side API keys have the highest level of access to read and/or update data, and as a best practice should only used by servers making API calls, where they can be kept secret. Using a server-side API key in a client-side environment is a security vulnerability, since malicious users of your site or app could potentially access your API key and use it to read or change data in your Iterable project.
Client-side API keys can access only a limited set of Iterable's API endpoints. However, since you can't prevent malicious users from accessing API keys stored in client-side code, it's a best practice to require JWT authentication for client-side API key, since it provides an additional layer of security.
When you use a client-side API key, Iterable provides the option to require JWT authentication. Client-side keys that do not require JWT authentication allow for anonymous, unauthenticated API access. This option is enabled by default when you select a client-side key. We strongly recommend selecting this option for all of your client-side keys.
To learn more about how to use JWT authentication, check out our guide, JWT-Enabled API Keys.
WARNING
Using a client-side API key without JWT authentication allows an attacker to call API methods on behalf of any other user in the project (provided they know or can guess their email address). For example, the attacker could get messages for other users, update a victim's email address to their own email, etc.
An attacker can also use unsecured client-side keys to unsubscribe any user whose email address is known or guessable.
Iterable API keys
Iterable provides five different types of API keys with varying levels of access. These keys are classified as either server-side or client-side.
Client-side keys
-
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
-
Web
NOTE
The Web API key enables API calls using Iterable's Web SDK, which is currently in beta testing. For more information, contact your customer success manager.
This type of API key can access the following endpoints:
POST /api/users/update
POST /api/users/updateEmail
POST /api/users/updateSubscriptions
POST /api/commerce/trackPurchase
POST /api/commerce/updateCart
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
POST /api/events/trackWebPushClick
POST /api/users/registerBrowserToken
Server-side keys
WARNING
Never embed a server-side API key in client-side code (whether JavaScript, a mobile application, or otherwise), since they can be used to access project data. Use these server-side API keys only when making API calls from your servers.
-
Read-only
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
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 generate.
If you're creating a client-side key, Require JWT authentication will be selected by default. When enabled, every call to Iterable's API using this key must also include a valid JWT as the value of an
Authorization
header (Bearer schema). For more information, read JWT-Enabled API Keys.You can de-select this security measure, however this is not recommended-see API key security above to learn why.
IMPORTANT
There are two things to know about enabling JWT authentication (or not):
- JWT authentication can only be enabled or disabled when you create the API key. This setting cannot be changed later.
- 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.
-
When you have finished adding a name, selected a type, and JWT authentication (if needed), click Create.
-
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 the API key. Then, click Update.
NOTE
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 any HTTP client in your application code, or using 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
NOTE
The key should be provided as an HTTP request header, not in the query string or request body. The header name is not case sensitive.
With Iterable's JavaScript SDK, iOS SDK, Android SDK or React Native SDK.
Comments
0 comments
Article is closed for comments.