See related
No related articles

API keys

Last Update: Sep 2024 • Est. Read Time: 3 MIN
To check plan availability, see the pricing page.

Integrations play a crucial role in utilizing Kustomer to its fullest potential. Many integrations and apps use API keys (also known as API tokens) to authorize Kustomer to send and receive data with external platforms. Your team can set the specificity of permissions on API keys used on integrations between Kustomer and third-party vendors, be they external or internal to your system.

Who can access this feature?
User typesAdmins can access the API keys settings page. Custom permission sets can grant Security permissions to let other users access the page.


In this article

Create an API key

Admins and other users with Security permissions can create and manage API keys from the Kustomer Settings.

To create a new API key:

  1. Go to Settings > Security > API Keys. 
  2. Select Add API Key.
  3. A popup will appear to edit your new API key. Start by giving the new API key a name. We always recommend using clear and illustrative names so that it's easy to know what function this API key performs if another member of your team reviews it later.
  4. Under Roles, select the roles required for your integration. You can select multiple values.
  5. In the Expires menu, select the number of days that the API key should remain valid before it expires.
  6. As an optional final step, you can enter a value in the CIDR IP Restriction box. This box restricts access to a token when outside of certain networks.
  7. Once satisfied with your selections, select Create to finish creating the new key.
  8. On the confirmation screen, you'll be shown your new key. For security reasons, this is your only chance to copy the key. Select Copy Token to copy the hash to your clipboard.

You can now add the API key to your app integration.

Best practices

When using API keys, keep the following in mind:

  • Tokens cannot be copied from the grid, they can only be copied when created. If you'd like to reference the API Key again, please copy and paste the API Key in a secure text editor.

  • API keys cannot be edited, only deleted.

  • A deleted token cannot be used to make requests to and from Kustomer.

  • It's important to be as specific as possible when naming the API key since your team may use dozens of tokens along the way.

  • When selecting roles, be mindful of what permissions are necessary for this token. For example, if you'd like to create customers from your admin portal, you can create a token with just org.user.customer.write .

  • When setting the days until the token expires, consider when a particular vendor or integration will need the token, such as a few days, weeks, or months. For e-commerce integrations such as Shopify, it may be necessary to set the token never to expire to avoid potential data loss if orders stop coming in due to key expiration.

  • The CIDR IP Restriction field should primarily be used for internal integrations. This token should only be used on a protected network like an internal admin portal. If needed, please consult with your engineering team to get the address.

Common API roles

Hundreds of API roles (or scopes) are available in Kustomer. This table contains a partial list of some of the most commonly used roles for API keys and app integrations.

API rolesDescription
org.user.setting.readView settings for users.
org.admin.setting.writeUpdate organization-wide settings.
org.permission.setting.readView settings for users.
org.permission.setting.updateUpdate settings for users.
org.permission.customer.readView customers.
org.permission.customer.createCreate customers.
org.permission.customer.updateUpdate customers.
org.permission.message.readView messages.
org.permission.message.createCreate messages.
org.permission.message.updateUpdate messages.
org.permission.conversation.readView conversations.
org.permission.conversation.createCreate conversations.
org.permission.conversation.updateUpdate conversations.
org.permission.team.readView teams.
org.permission.team.createCreate teams.
org.permission.team.updateUpdate teams.
org.permission.user.read
View users.
org.permission.user.createCreate users.
org.permission.user.updateUpdate users.
org.permission.kobject.readView KObjects/custom objects.
orb.permission.kobject.createCreate KObjects/custom objects.