Advanced license required
Features described on this page require the Xperience by Kentico Advanced license tier.
Headless channels encapsulate content that is intended to be served using HTTP requests and GraphQL (opens in a new tab). Such headless content can be displayed or otherwise consumed by various types of applications, services or websites (e.g., mobile apps, external websites, single-page applications running within Xperience, etc.).
Every headless channel has its own GraphQL API endpoint (opens in a new tab), which is secured by one or more API keys. Each channel also has its own application in the Xperience administration, where editors can manage content intended for headless distribution. The content is stored in items based on headless content types. These headless items can also reuse content from Content hub that is shared between all types of channels.
To start using the headless API:
To create a new headless channel:
Channel name – the name of the channel displayed in the administration. Also sets the name of the channel application where users manage the website's headless items and edit content.
(Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.
Channel type – select Headless as the channel type.
Channel size – channels are available in two sizes: Standard and Micro. Standard channels may contain an unlimited number of content items. Microchannels are limited to 20 items, each of which can link an unlimited number of reusable content items.
Primary language – a language configured in the Languages application that specifies which language version of headless items is retrieved if no language is specified in the query.
Preview URL – URL of the environment in which you want to preview the headless content, shared for all headless items in the channel. The URL is accessible via the Preview button in the headless channel application.
As the Preview URL is common for the whole channel (it is currently not possible to assign a specific URL for each headless item separately), we recommend that developers design the target environment of the Preview URL as a link tree for easier navigation to individual headless items.
After you create a headless channel, a GraphQL API endpoint is created. However, the endpoint is inactive until you create at least one content type for headless items and assign it to the channel on the Allowed content types tab.
Every headless item uses a specific content type. The content type defines the fields that users can edit when creating headless items.
To create headless items under a channel, you need to prepare suitable content types and allow them for the channel:
Headless items of the selected content types can now be created in the headless channel application.
You can freely change between the microchannel and standard channel size of existing channels via the General tab. Additionally, changing standard channels to microchannels does not cause any data loss in case the converted channel exceeds microchannel limits. However, you will receive a license violation warning if the resulting channel or item count oversteps the limits of your license for that particular channel type.
The API endpoints of headless channels are available on all domains where the Xperience project is running. This includes:
Administration interface domain (including the System domains of SaaS environment deployments)
The GraphQL API endpoint is available on the system and default channel domains of any SaaS deployment that is publicly available. Keep this in mind when designing your project's security.
Service domains of email channels
To find the URL on which a headless channel's endpoint is available, follow these steps:
Select one of the domains on which the endpoint is available.
Navigate to the Channel management application → select a headless channel → General tab and copy the endpoint URL path in the GraphQL API endpoint field.
The GraphQL API endpoint URL is in format <domain>/<GraphQL API endpoint path>, e.g.:
https://example.com/graphql/09114e33-7578-4152-af81-62677bcca740
The endpoint slug ('/graphql' by default) can be configured.
The headless API can be configured (for all headless channels) by setting the following keys in the application's configuration file (appsettings.json by default):
CMSHeadless
Enable – a boolean value that specifies whether headless channel endpoints are enabled (both GraphQL API and Tracking API endpoints). The default value is true.
EnableTracking – a boolean value that specifies whether Tracking API endpoints are enabled. Allows you to disable the tracking API while keeping the GraphQL API enabled. The default value is true.
EnableComplexity – a boolean value that specifies whether complexity analysis (opens in a new tab) is enabled.
EnableUnionQueryOptimization – a boolean value that specifies whether performance optimizations are enabled for GraphQL queries that retrieve data with fields linking to a large number of possible content types (e.g. fields with the Pages and reusable content data type). This prevents timeout errors for queries that load data with a very large number of linked content types. The default value is true.
MaxFieldCycleDepth – specifies the maximum allowed depth of field cycles in a GraphQL query. The default value is 5.
AllowIntrospection – a boolean value that specifies whether GraphQL introspection (opens in a new tab) is enabled (__schema queries and GUI tools for exploring the schema). False by default.
GraphQlEndpointPath – specifies the slug used in headless channel GraphQL endpoint URLs. You need to include the leading slash ('/'). The default value is /graphql.
CorsAllowedOrigins – specifies domains that are allowed origins for CORS (opens in a new tab) (Cross-Origin Resource Sharing). See Retrieve headless content to learn more.
We recommend configuring allowed origins for CORS in the Settings application within the Xperience administration, via the Content → Headless → Allowed origins setting. The setting overrides any values set in your application's configuration file or startup options.
CorsAllowedHeaders – indicates which HTTP headers are allowed for content retrieval requests. If not set, all headers are allowed by default. See Retrieve headless content to learn more.
Caching – an object that contains options which allow you to customize caching behavior for headless content. The default values provide optimal caching performance for most projects.
Enable – a boolean value that specifies whether caching is enabled. The default value is true.UseRequestCacheControlHeaders – a boolean property that specifies whether caching respects the Cache-Control header of individual requests. The default value is true.AddResponseCacheControlHeaders – a boolean property that specifies whether caching sets the Cache-Control response header. The default value is true.UseCacheDependencies – a boolean property that specifies whether caching uses cache dependencies to flush the cache when data in a cached response changes. The default value is true.AbsoluteExpiration – specifies the maximum expiration time for a cache entry in minutes. The default value is 12 hours.SlidingExpiration – specifies a sliding expiration date for cache entries in minutes. Cannot exceed the value of AbsoluteExpiration. The default value is 1 hour.SizeLimit – maximum size for in-memory cache in bytes. The default value is 100 megabytes.{
...
"CMSHeadless": {
"AllowIntrospection": true,
"GraphQlEndpointPath": "/api",
"Caching": {
"AbsoluteExpiration": "360"
}
}
}If you wish to use a different provider (opens in a new tab) for your project configuration (e.g., Azure Key Vault (opens in a new tab)), you can map the configuration in your project's startup file (Program.cs) using the HeadlessOptions class, with properties matching the configuration keys described above:
using Kentico.Xperience.Headless;
builder.Services.AddKentico(...);
builder.Services.Configure<HeadlessOptions>(options =>
{
// Enables introspection in the Development environment
options.AllowIntrospection = builder.Environment.IsDevelopment();
// Changes the endpoint slug to 'api'
options.GraphQlEndpointPath = "/api";
// Changes the maximum expiration of a cache entry to 6 hours
options.Caching.AbsoluteExpiration = TimeSpan.FromHours(6);
});Preview URL overrides enable you to better separate the Preview URL between different environments. The overrides can be configured programmatically using the HeadlessChannelUrlOptions class and ASP.NET Core configuration providers (opens in a new tab).
For example, when configured via appsettings.json:
{
...
"HeadlessChannelUrls": {
"UrlOverrides": {
"DancingGoatHeadless": {
"PreviewUrl": "https://preview.domain.com",
}
}
}
}using Kentico.Xperience.Headless;
builder.Services.AddKentico(...);
// Apply the Preview URL overrides configuration from appsettings.json
builder.Services.Configure<HeadlessChannelUrlOptions>(builder.Configuration.GetSection("HeadlessChannelUrls"));Where DancingGoatHeadless is the code name of the headless channel to configure. This configuration takes priority over the channel options set via the General tab in the Xperience user interface.
You can also make use of the options pattern (opens in a new tab) to set different overrides per environment (opens in a new tab) by introducing corresponding appsettings.environment.json files. The following example sets the override to localhost when the project is run under the Development environment.
{
"HeadlessChannelUrls": {
"UrlOverrides": {
"DancingGoatHeadless": {
"PreviewUrl": "localhost",
}
}
}
}Headless channel GraphQL API endpoints are secured. All requests to an endpoint need to have an Authorization header storing a valid and enabled API key. The API keys are managed in Xperience for each headless channel.
Permission requirements
To manage API keys on the API keys tab, users need to have a role with the Manage headless channel API keys permission for the Channel management application. Contact your project's administrator if you cannot access the application.
To create a new API key:
Open the Channel management application in the Xperience administration.
Select a headless channel.
Switch to the API keys tab.
Select New key.
Enter the API key name.
Select the Access type of the key.
(Optional) If you want to create the key as disabled (e.g., when you only want to prepare the key now but enable it later), clear the Enabled checkbox.
Generate the key.
Copy the API key and store it in a safe location.
Select Continue after you have copied the key and stored it in a safe location.
You need to authenticate every request that retrieves headless content by adding the following HTTP header:
Authorization: Bearer <ApiKey>The headless API provides different API keys for various types of scenarios.
For content retrieval requests against the channel's GraphQL API endpoint you can use the following Access types:
Headless content - Draft – Grants access to the latest available version of headless items, i.e., items in the Draft step or a custom workflow step (if available), or the Published status.
Headless content - Published – Grants access only to Published headless items. When retrieving headless content using a key with this Access type, items without a published version will not be included in the retrieved data at all.
The type of granted access applies transitively to all linked items of accessed headless content. That is, when using a Headless content - Draft key, the linked items will also be accessed in their latest available version. Alternatively, when using a Headless content - Published key, only published linked items will be accessed.
For tracking API requests you can use the following Access type:
To disable an API key:
After you disable an API key, any services or applications using this key have their access immediately revoked and any further requests using this API key will result in an authorization error.
The API key needs to be sent in the HTTP header of all GraphQL requests. If sent from a client API on a public web page, it can be seen by anyone. It is recommended to not add the API key to request headers directly in the client API, but to instead use a backend proxy server to add the Authorization request header and forward the requests to the GraphQL API endpoint.
For more information, see Retrieve headless content.