Securing public access

When using the public Delivery API, you cannot use it to manage the user roles and their access to particular content in your application. With secure access enabled, you can protect your content by requiring an API key with each request and configuring content authorization in your app.

Premium feature

Secure access to the Delivery API requires a Professional plan or higher. See Pricing for more details.

Table of contents

Secure access to the Delivery API allows you to use two concurrent API keys, Primary and Secondary.

Note: For continuous use, we recommend using the Primary key to authenticate your API requests and only using the Secondary key when revoking the Primary key to prevent your site from any downtime. For more information, see the Revoking the API keys section of this tutorial.

Primary vs. Secondary key

The following instructions work equally for both the Primary key and the Secondary key.

Enabling secure access

Secure access to the Delivery API is disabled by default for new projects and you need to activate it. By activating the secure access, the system will also generate new API keys, Primary and Secondary.

In Kentico Cloud, choose a project.

From the app menu, choose Project settings {@icon-settings@}.

Under Development, choose API keys.

In the Delivery API box, click the switch to activate secure access.

Delivery API with secure access enabled.

You will mainly use the Primary key to authenticate your requests. Both API keys are generated per project and have no expiration date. For more information, see secure access in our API reference.

Getting API key

Every request to the Delivery API with secure access enabled must be authenticated with an API key. This key is unique to each project in Kentico Cloud.

To get the key:

In Kentico Cloud, choose a project.

From the app menu, choose Project settings {@icon-settings@}.

Under Development, choose API keys.

In the Delivery API box, click Copy to clipboard {@icon-copy@} to copy the API key.

You can now use the key to authenticate your requests to the API.

Authenticating requests

Every request you make must come with an API key in the {~Authorization~} header. The {~Authorization~} header uses the following format: {~Authorization: Bearer <YOUR_API_KEY> ~}

Retrieving secured content

Security tips

Here are some quick tips to help you while using the secure access to the Delivery API:

Only regenerate one key at a time to prevent downtime.

Do not store API Keys in the source code.

Encrypt the key when storing it.

Regenerate your API keys periodically.

The older a key is, the higher the probability it could have been compromised.

To retrieve a specific content item from Kentico Cloud via API, you need to use the project ID and the content item's codename in your request. See Getting content to find out how you can get these two values.

The Delivery API uses the following URI to retrieve the published content:

{~https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/~}

Once you have the project ID and content item codename, you can retrieve the published content item.

For example, to retrieve the content of a published article named "On Roasts" from the sample project, you can use the following request.

Note: Modular content (content linked using Rich text or Linked items elements) was omitted from the response for brevity.

You can limit the retrieved data, for example, retrieve only specific elements, by using optional query parameters. See the API reference for the Delivery API to learn more about the available options and methods.

Revoking the API keys

In certain situations, you may need to revoke one of the API keys and generate a new one. For example, when you suspect unauthorized key usage or when a developer with access to the API key has left your company.

For the reasons above, one or both of the API keys can be regenerated. Activating a new key will immediately replace the old key, making it useless. Requests made with a revoked API Key will then receive a 401 Unauthorized HTTP status code in the response.

Note: First you need to have the secure access for the Delivery API enabled in the UI.

In Kentico Cloud, choose a project.

From the app menu, choose Project settings {@icon-settings@}.

Under Development, choose API keys.

Regenerate the Secondary key as this ensures it's new and secure.

Change all applications using the secured Delivery API to use the newly regenerated Secondary key.

Validate all applications using the Secondary key are functioning correctly.

Regenerate the Primary key to make sure any unauthorized users cannot use this key to access the application.

(Optional) Switch back to using the regenerated Primary key in all of your applications.

The last step is optional as switching back to the regenerated Primary key might seem unnecessarily complicated. The reason behind this is simple – you can easily keep track of the API key you are currently using for your application. If you only use the Secondary key to prevent downtime when revoking the Primary key, it can keep things simple in the long run.