API key management

Manage API keys

You can create and manage your API keys in Project settings > API keys. The list of API keys shows you the API keys you can access.

Delivery API keys

Use Delivery API keys to retrieve content from Delivery REST API and Delivery GraphQL API.

• Get published content from environments with secure access enabled. If secure access is disabled, your content is publicly accessible without an API key.
• Preview the latest content from environments. You always need an API key to preview content.

Delivery API keys are shared between all project managers. Check the Delivery API reference for more details about Delivery API keys.

Management API keys

Use Management API keys and Personal API keys to manage your project environments and their content via Management API. For example, perform content migrations or integrate with third-party services. Whenever you make a content change via API, the change is tied to the specific API key and can be seen in the version history and audit log.

• With Management API keys, you’ll see the API key’s name.
• With Personal API keys, you’ll see the API key’s owner name.

Check the Management API reference for more details about Management API keys.

Who can manage API keys?

The user who can manage an API key can view the API key value, change the API key settings, and revoke the API key.

• Delivery API keys are managed by project managers. Project managers can specify additional users who can view the API key value.
• Management API keys are managed by project managers. Project managers can specify additional users who can view the API key value.
• Personal API keys are managed by their owners. These can be project managers and users with the Create a personal API key permission. Project managers can revoke other users’ personal API keys, but cannot see the API key value.

Create Delivery API keys

You can use multiple Delivery API keys in your projects. For example, you can have a Delivery API key for previewing content and another for getting published content. The benefit of using multiple Delivery API keys is having integration-specific and application-specific keys. You can mitigate the impact of API key expiration or rotation by using dedicated Delivery API keys. To create a Delivery API key:

1. In Project settings > API keys > Delivery API keys, click Create Delivery API key.
2. (Optional) In Expiration date, choose when you want the API key to expire. By default, the API key expires in one year.
3. In Name, type the name of the API key.
4. (Optional) In Users with access to this API key, allow specific users to view and copy the API key. By default, all project managers can view the API key.
5. In Delivery API access, specify the access granted by the API key.
   • For retrieving published content from environments with secure access enabled, select Secure access.
   • For previewing the latest and unpublished content, select Content preview.
6. In Limitations, adjust the API key scope to specific environments.
7. Click Save changes.
8. In API key, click to copy the API key value.

Create Management API keys

You can use multiple Management API keys in your projects. For example, you can use one Management API key to integrate a translation management system, and another API key for content migrations. To create a Management API key:

1. In Project settings > API keys > Management API keys, click Create Management API key.
2. (Optional) In Expiration date, choose when you want the API key to expire. By default, the API key expires in six months.
3. In Name, type a human-friendly name describing the API key’s purpose. For example, Translation management or Team notifications.
4. (Optional) In Users with access to this API key, allow specific users to view and copy the API key. By default, only project managers can view the API key.
5. In Limitations, adjust the API key scope to specific environments.
6. In Permissions, select at least one permission for the API key.
7. Click Save changes.
8. In API key, click to copy the API key value.

Management API key permissions

The Read content allows the API key to:

• Get content items.
• Get content item variants.
• Validate content

The Create, edit, and delete content permission includes the Read content permission and allows the API key to:

• Add content items.
• Change workflow of content item variants.
• Create new versions of content item variants.
• Delete content items.
• Delete content item variants.
• Publish, schedule, and unpublish content item variants.
• Upsert content items.

The Read assets permission allows the API key to:

• Get assets.
• Get asset folders.
• Get asset renditions of an asset.

The Create, edit, and delete assets permission includes the Read assets permission and allows the API key to:

• Add assets and files.
• Add asset folders.
• Add asset renditions.
• Delete assets.
• Delete asset folders.
• Modify asset folders.
• Modify asset renditions.
• Upsert assets.

The Manage content model permission allows the API key to:

• Add, get, modify, and delete content types.
• Add, get, modify, and delete content type snippets.
• Add, get, modify, and delete taxonomy groups.

The Manage environment settings permission allows the API key to:

• Add, get, and modify languages.
• Add, get, modify, and delete spaces.
• Get and modify collections.
• Get and modify preview URLs.
• Get and modify the live preview's status.
• Add, get, and delete webhooks.
• Add, get, and delete legacy webhooks.
• Add, get, modify, and delete workflows.

The Manage environments permission requires that the API key has access to all environments and allows the API key to:

• Clone environments.
• Delete environments.
• Get information about environments and their cloning status.
• Mark environments as production.
• Rename environments.

The Manage custom apps permission allows the API key to add, get, modify, and delete custom apps.

Create Personal API keys

Project managers and users with the Create a personal API key permission can create their own Personal API keys to use Management API. Each eligible user can have only a single personal API key. To create a Personal API key.

1. In Project settings > API keys > Management API keys, click Create Personal API key.
2. (Optional) In Expiration date, choose when you want the API key to expire. By default, the API key expires in six months.
3. Click Save changes.
4. In API key, click to copy the API key value.

Set API key expiration

The default and recommended API key expiration lengths differ for Delivery API and Management API.

• For Management API keys, the default expiration length is six months. The expiration length can vary from 1 minute to 2 years.
• For Delivery API keys, the default expiration length is one year. The expiration length can vary from 1 minute to 5 years.

Before the API keys expire, the users who can manage the API keys are notified via email.

Regenerate API keys

When might you need to regenerate your API keys? 

• You suspect unauthorized API key usage, for example, after a user leaves your company. In such cases, switch to a new API key in your apps and regenerate your existing API key.
• Users are removed from your project’s environment or subscription. Depending on the user’s access level, you might want to regenerate the shared Delivery API keys.
• You receive a notification about an upcoming expiration of your API key.

When you regenerate your API key, the API key is revoked after a few minutes, and you get a new API key immediately.

1. In Project settings > API keys.
2. On either the Delivery API keys or Management API keys tab, choose an API key to view its details.
3. In API key, click .

Revoke API keys

If you no longer need an API key, you can revoke it to prevent further access. For example, when you stop using an integration and don’t plan on replacing it or its associated API key. When you revoke an API key, the API key becomes invalid and is removed from the list of API keys. The revocation process can take up to a couple of minutes. Any requests made with a revoked API key result in the 401 Unauthorized error.

1. In Project settings > API keys.
2. On either the Delivery API keys or Management API keys tab, choose an API key to view its details.
3. Click Revoke.
4. In the confirmation dialog, click Revoke.