API Keys

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.

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

  • POST /api/users/update
  • POST /api/events/track
  • POST /api/commerce/trackPurchase
  • POST /api/commerce/updateCart
  • POST /api/events/trackWebPushClick
  • POST /api/users/registerBrowserToken

• 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

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

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

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

5. When you have finished adding a name, selected a type, and JWT authentication (if needed), click Create.

   

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

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.

# Deleting API keys

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

There are various ways to use Iterable API keys:

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

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

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

# Further reading

• Iterable's API documentation
• API Overview and Sample Payloads
• JWT-Enabled API Keys