# API keys > Your team can set the specificity of permissions on API keys used on integrations between Kustomer and third-party vendors. Source: https://support.kustomer.com/en_us/api-keys-SJs5YTIWX Last updated: 2026-06-08T16:00:02.069Z 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 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 * [Understand API roles](#high-level) * [Role access levels](#role) * [Common API roles](#common-api-roles) * [Create an API key](#create) * [Delete an API key](#delete) * [Best practices](#best-practices) ### Understand API roles at a high level When creating an API key, you assign one or more roles to define what the key can access and do. Each role is structured using a dot notation pattern, which makes it easier to tell what the role allows. `org.admin.*` Roles with this prefix grant full access to admin-level tools and configuration. These are typically used to manage the organization: users, teams, workflows, integrations, and system settings. If your API key needs to simulate or manage what an admin can do in Kustomer, this is the prefix to use. `org.user.*` These roles are modeled after a typical agent or user in the system. They usually allow access to the conversation timeline, customer profiles, and standard actions like tagging, replying, and closing conversations. Use these roles when the API key is meant to behave like an agent, not an administrator. `org.permission.*` These roles grant specific, narrowly scoped capabilities that may not be tied to a user or admin role directly. They’re often used to enable access to particular features (like audit logs or custom object APIs) without exposing broader functionality. If you need to grant access to something precise, without elevating the key to a full user or admin role, this is the most flexible option. ### Role access levels Roles come in different levels of access, based on the suffix at the end: * `.read` – View data * `.create` – Add new records * `.update` – Modify existing records * `.delete` – Remove records * `.write` – Often includes create/update/delete (but not always `read`) If you assign a role like `org.user.brand.read`, the API key can only view brand data. If you assign `org.user.brand.create`, it can only add new brands, and so on. The **top-level role**, like `org.user.brand`, grants **full access** to the resource. That typically includes all of the above: `read`, `create`, `update`, and `delete`.  We recommend using the granular roles if you want tight control over what the API key can do. The following table shows an example of the type of access given by role. Role Access granted `org.user.brand` Full access (read, create, update, delete) `org.user.brand.read` View brand data only `org.user.brand.create` Add new brands `org.user.brand.update` Modify brand details `org.user.brand.delete` Remove brand entries `org.user.brand.write` Usually includes create/update/delete (but not always read) ### 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. ### 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. **Note:** You cannot change the roles once the key is created. 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.  ### Delete an API key To remove an API key, select **Delete** next to the key. ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/bac7cb7601012c0f1a43477cf41b235d.png) ### 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, 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. ### **Change the avatar for an API key user** Each API key is associated with a machine user account. Messages sent through the API display this user's avatar in conversations. By default, the system assigns a random profile picture. To change the avatar, send a PUT request to the Users API endpoint for the machine user. Include the image URL in the request body: `PUT https://{orgname}.api.kustomerapp.com/v1/users/{userId}` `` ` ` `` `` `{` ``   `` `"avatar": "https://example.com/your-image.png"` `` `` `}` `` To find the machine user ID associated with an API key, check the ****Created By**** field on a message sent through that key.