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 keys, projects, and data centers

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.

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

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

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

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

# Client-side keys

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

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

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

  1. From Iterable's API documentation:

    Paste your API key in the Authentication Header input (in the upper-left corner of the page), and click *Apply. Then, you can make API calls as necessary, right from the docs.

  2. 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 or Api_Key request header. 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

    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.

  3. With Iterable's Web SDK, iOS SDK, Android SDK or React Native SDK.

# 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