Articles in this section

API Keys

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 permissions and security

API keys are secrets that open a gateway to read and/or update the data contained in your Iterable project. API keys have permissions that determine what the key can and cannot do. Most API key permissions are governed by the type of API key you create.

Before you make an API key, it's imperative to consider the level of security necessary and decide on the correct API key type for your use case. If you are using a client-side API key, you should also consider additional security settings (Event creation and JWT authentication).

# API keys and their environments

Every Iterable API key is associated with a specific Iterable project, which means that it's also associated with a specific data center:

  • API keys created in USDC-based Iterable projects can only be used with Iterable's USDC-based API endpoints (base URL: https://api.iterable.com). For API docs that interact with these endpoints, see https://api.iterable.com/api/docs.

  • API keys created in EDC-based Iterable projects can only be used with Iterable's EDC-based API endpoints (base URL: https://api.eu.iterable.com). For API docs that interact with these endpoints, see https://api.eu.iterable.com/api/docs.

# User associated with API key operations

When you use an API key to update or create a resource, the operation is usually associated with the user who created the Iterable project.

For certain endpoints, the user associated with the operation can be overridden with the createdByUserId or the creatorUserId parameter (where specified) as an optional request parameter.

For example:

  • Snippets APIs accept the createdByUserId parameter to specify the user who created the snippet.
  • Templates APIs accept the creatorUserId parameter to specify the user who created the template.

# 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.

# Event Creation

IMPORTANT

Currently, the Event creation permission is only available to newly created Iterable organizations as of August 30, 2022. Client-side API keys for existing orgs and projects created before this date don't require this permission to create new events.

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 eventName will 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.

NOTE

For more information about managing your project's data schema, read Data Schema Overview.

# JWT authentication

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.

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 keys to unsubscribe any user whose email address is known or guessable.

# Types of 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.

# 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:

# Server-side

Server-side API keys can access all of Iterable's API endpoints, except for:

# 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:

# Web

This type of API key can access the following endpoints:

# Creating API keys

To create API keys for an Iterable project:

  1. Sign in to an Iterable project as an org admin or as a member that has the Manage Integrations project permission.

  2. 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.

  3. Click New API Key.

  4. 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.

  5. (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.

    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.

  6. When you have finished, click Create.

    Creating a new API key

  7. In the Copy Your New API Key window, copy the API key:

    Copying an 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:

    Copying an API key and its JWT secret

    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.

# Using API keys

# Providing API keys in HTTP requests

With any HTTP client in your application code, or using a third-party tool such as Postman, Insomnia or curl, the API key must be provided as an HTTP request header.

To do this, set the API key as the value for an Api-Key or Api_Key request header. The parameter name is not case sensitive.

For example:

curl -H "Api-Key: <YOUR_API_KEY>" https://api.iterable.com/api/users/user@example.com

or

curl -H "Api-Key: <YOUR_API_KEY>" https://api.eu.iterable.com/api/users/user@example.com

# Exceptions for legacy projects

Certain legacy projects have exceptions that still allow API keys to be provided in the query string or request body. However, this is not a best practice and it is not supported for most projects.

IMPORTANT

Beginning November 10, 2025, API calls that provide the key in the query string or request body will be subject to stricter rate limiting. This change only impacts legacy projects with exceptions to make API calls using the query string or request body.

To avoid being impacted by this change, modify your application code to use API keys as HTTP request headers instead of using the query string or request body.

# Using API keys with Iterable's SDKs

You can use an Iterable API key with Iterable's Web SDK, iOS SDK, Android SDK React Native SDK.

Make sure to use a client-side API key with the SDKs.

# Editing API keys

When you edit an API key, you can change the following:

  • Name

  • 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:

  1. Navigate to Integrations > API Keys.

  2. Click Edit for the API key you'd like to modify.

  3. 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.

# 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:

  1. Navigate to Integrations > API Keys:

  2. 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:

  1. Navigate to Integrations > API Keys:

  2. Find the API key to delete. In its row, click the down arrow and select Delete Key.

  3. Confirm the deletion.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

Support docs

Related articles