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 document describes the types of API keys Iterable provides, how to create them and how to use them.

# Table of contents

# Types of API keys

Iterable provides four different types of API keys, each of which can access a different subset of Iterable's API endpoints:

• 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

  If possible, when using a mobile API key, we recommend using JWT authentication for additional security.

• Read-only

  WARNING

  Never embed read-only API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access project data. Use read-only API keys only when making API calls from your servers.

  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

  WARNING

  Never embed server-side API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access all of your project's data. Use server-side API keys only when making API calls from your servers.

  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 create. Then, click Create.

   

   To use JWT authentication with a mobile API key, check Require JWT Authentication on the bottom of the window. 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). For more information, read JWT-Enabled API Keys.

   WARNING

   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. 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 an API key. Then, click Update.

   TIP

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

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