Iterable's API can be used to interact with a project's users, templates, campaigns, journeys, and more. To authenticate with the API, you must use an API key.
This guide describes the types of API keys Iterable provides, their permissions, how to manage 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 for client-side keys, decide on security settings (Event creation and JWT authentication).
Selecting a key type
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 considered 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. You can also choose to allow a limited time frame to create new event definitions while your project is in development.
Client-side key security settings
Available security settings for client-side API keys include Event creation and JWT authentication. These options will appear once you select a client-side type of API key.
Currently, the Event creation permission is only available to newly created Iterable organizations as of 5:00pm PST on August 29, 2022.
Client-side API keys for existing orgs and projects can create new custom event
definitions, at any time, simply by sending an event track API call with a new
eventName, until this permission is rolled out to your org.
It's important to audit your API use at this time and ensure you have correct measures in place to avoid disruption when these permissions change.
For more information on our phased release plan, see our release notes.
This setting defines whether an API key can create new custom event definitions in your project. Regardless of the selection, keys can still track known events as defined in your project's Custom events.
Block event track calls: When selected, the API key cannot create new custom event definitions. API calls tracking events with a unknown event name will be ignored, and the data will not be stored in your project as a tracked event.
Allow event track calls: This permission enables a client-side API key to post new custom event definitions for the specified period of time, up to 14 days in the future.
Until expiration, API calls tracking custom events with a previously untracked value for
eventNamewill create a new event definition in your project's Custom events.
Once the period expires, the permission will toggle back to a blocked state.
If you need additional time to create events with your API key, you can edit the API key later and extend the permission for another 14 days.
In addition to Event creation permission for API keys, projects also have a general setting to allow new custom events into the system. This project-level permission take precedence over the API key permission. If this setting is disabled, then you will not be able to create new event definitions from any API key, regardless of a key's Event creation permission.
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).
When you're creating a client-side key, JWT authentication is selected by default. Client-side keys that do not require JWT authentication allow for anonymous, unauthenticated API access. We strongly recommend selecting this option for all of your client-side keys.
JWT authentication security cannot be changed after you create your API key. If your key has JWT enabled and you need a key that does not require JWT, or vice-versa, you will need to create a new key.
To learn more about how to use JWT authentication, check out our guide, JWT-Enabled API Keys.
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 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.
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:
Server-side API keys can access all of Iterable's API endpoints, except for:
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:
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 API Key window, enter a name for the key and select the type of API key you'd like to generate.
It's a good idea to create a descriptive name for the API key so you know what the key is used for. This can be helpful if you have security reasons to disable or delete keys later, or for when you simply need to find and update a key later.
(Client-side only) If you have selected a client-side key type, you will see additional settings:
Event Creation - Block creation of new event definitions, or allow them for up to 14 days in the future. For more information on this setting, see Event creation above.
JWT Authentication - this is selected by default and highly recommended. To learn more about why this is encouraged, see JWT authentication above.
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, 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
When you edit an API key, you can change the following:
Event Creation (client-side keys) - This permission can be extended for 14 days at a time.
API Keys that were created prior to August 5, 2022 have legacy permissions for event creation and have no restrictions when creating new event definitions. When you edit a legacy key, you will see a notice and have the option to update the key to the new permission settings and either block event creation, or apply an expiration period for event creation. You cannot change this permission back to the legacy setting once this has been set.
JWT authentication can only be changed at the time the key is created. If you need a key with or without this security, create a new key.
To edit 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.
You cannot change the type of an API key that requires JWT authentication.
Disabling API keys
Disabling keys can be helpful when there are security reasons to restrict access for specific applications and/or when troubleshooting problems with your data.
Disabled keys can be re-enabled later.
To disable an API key:
Navigate to Integrations > API Keys:
Find the API key to delete. In its row, click the down arrow and select Disable Key.
Deleting API keys
This is a permanent action. Only delete an API key if it is no longer in use. If you are not sure, you can instead disable it.
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
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.
curl -H "Api-Key: 7edf98199a5b49fa8bd016622432632a" https://email@example.com
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.