API keys
Last Update: Sep 2024 • Est. Read Time: 3 MINIntegrations 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 types | Admins 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:
- Go to Settings > Security > API Keys.
- Select Add API Key.
- 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.
- Under Roles, select the roles required for your integration. You can select multiple values.
- In the Expires menu, select the number of days that the API key should remain valid before it expires.
- 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.
- Once satisfied with your selections, select Create to finish creating the new key.
- 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 roles | Description |
org.user.setting.read | View settings for users. |
org.admin.setting.write | Update organization-wide settings. |
org.permission.setting.read | View settings for users. |
org.permission.setting.update | Update settings for users. |
org.permission.customer.read | View customers. |
org.permission.customer.create | Create customers. |
org.permission.customer.update | Update customers. |
org.permission.message.read | View messages. |
org.permission.message.create | Create messages. |
org.permission.message.update | Update messages. |
org.permission.conversation.read | View conversations. |
org.permission.conversation.create | Create conversations. |
org.permission.conversation.update | Update conversations. |
org.permission.team.read | View teams. |
org.permission.team.create | Create teams. |
org.permission.team.update | Update teams. |
org.permission.user.read | View users. |
org.permission.user.create | Create users. |
org.permission.user.update | Update users. |
org.permission.kobject.read | View KObjects/custom objects. |
orb.permission.kobject.create | Create KObjects/custom objects. |