The Content Delivery API delivers headless capabilities built directly into Umbraco. It allows you to retrieve your content items in a JSON format and use your preferred technology to present them in different channels.

The feature preserves a friendly editing experience in Umbraco while ensuring a performant delivery of content in a headless fashion. With the different extension points, you can tailor the API to fit a broad range of requirements.

Getting Started

The Delivery API is an opt-in feature in Umbraco. It must be explicitly enabled through configuration before it can be utilized.

Enable the Content Delivery API

When creating your project, you can enable the Delivery API using the --use-delivery-api or -da flag. This will automatically add the necessary configuration to your project.

dotnet new umbraco -n MyProject -da

You can also enable the Delivery API at a later point by following these steps:

1. Open your project's appsettings.json.

2. Insert the DeliveryApi configuration section under Umbraco:CMS.

3. Add the Enabled key and set its value to true.

4. Open Program.Cs

5. Add .AddDeliveryApi() to builder.CreateUmbracoBuilder()

{
    "Umbraco": {
        "CMS": {
            "DeliveryApi": {
                "Enabled": true
            }
        }
    }
}

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

Once the Content Delivery API is enabled, the next step is to rebuild the Delivery API content index (DeliveryApiContentIndex). This can be done using the Examine Management dashboard in the Settings section of the Umbraco Backoffice.

1. Access the Umbraco Backoffice.

2. Navigate to the Settings section.

3. Open the Examine Management dashboard.

4. Scroll down to find the Tools.

1. Use the Rebuild index button.

Once the index is rebuilt, the API can serve the latest content from the multiple-items endpoint.

Additional configuration

When the Delivery API is enabled in your project, all your published content will be made available to the public by default.

A few additional configuration options will allow you to restrict access to the Delivery API endpoints and limit the content returned.

{
    "Umbraco": {
        "CMS": {
            "DeliveryApi": {
                "Enabled": true,
                "PublicAccess": true,
                "ApiKey": "my-api-key",
                "DisallowedContentTypeAliases": ["alias1", "alias2", "alias3"],
                "RichTextOutputAsJson": false
            }
        }
    }
}

Find a description of each of the configuration keys in the table below.

Concepts

Before exploring the API endpoints detailed below, there are a few concepts to know.

{
  "name": "string",
  "createDate": "2023-06-23T11:31:07.281Z",
  "updateDate": "2023-06-23T11:31:07.281Z",
  "route": {
    "path": "string",
    "startItem": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "path": "string"
    }
  },
  "id": "11fb598b-5c51-4d1a-8f2e-0c7594361d15",
  "contentType": "string",
  "properties": {
    "property1Alias": "string",
    "property2Alias": 0,
    "property3Alias": true,
    "property4Alias": [],
    "property5Alias": {},
    "property6Alias": null
  },
  "cultures": {
    "cultureIsoCode1": {
      "path": "string",
      "startItem": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "path": "string"
      }
    },
    "cultureIsoCode2": {
      "path": "string",
      "startItem": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "path": "string"
      }
    }
  }
}

{
  "route": {
    "path": "/articles/2023/getting-started",
    "startItem": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "path": "docs-portal"
    }
  }
}

GET /umbraco/delivery/api/v2/content/item/articles/2023/getting-started
Start-Item: docs-portal

GET /umbraco/delivery/api/v2/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
Preview: true
Api-Key: my-api-key

GET /umbraco/delivery/api/v2/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
Accept-Language: en-US

Endpoints

The Delivery API output can represent a specific content item or a paged list of multiple items.

Gets a content item by id

GET /umbraco/delivery/api/v2/content/item/{id}

Returns a single item.

Path Parameters

Query Parameters

Headers

Gets a content item by route

GET /umbraco/delivery/api/v2/content/item/{path}

Returns a single item.

Path Parameters

Query Parameters

Headers

Gets content item(s) by id

GET /umbraco/delivery/api/v2/content/items

Returns single or multiple items by id.

Query Parameters

Headers

Gets content item(s) from a query

GET /umbraco/delivery/api/v2/content

Returns single or multiple items.

Query Parameters

Headers

All endpoints are documented in a Swagger document at {yourdomain}/umbraco/swagger. This document is not available in production mode by default. For more information read the API versioning and OpenAPI article.

Query parameters

The Content Delivery API provides query parameters that allow you to customize the content returned by the API. The relevant query parameters for each endpoint are already specified in the corresponding documentation above.

In addition to standard parameters like skip and take, the API provides different possibilities for the value of the expand, fields, fetch, filter and sort parameters. Below are the options that are supported out of the box.

GET /umbraco/delivery/api/v2/content?fetch=children:dc1f43da-49c6-4d87-b104-a5864eca8152

GET /umbraco/delivery/api/v2/content?filter=contentType:article&filter=name:guide&skip=0&take=10

GET /umbraco/delivery/api/v2/content?filter=contentType:article&filter=createDate>:2023-01-01&filter=createDate<2024-01-01&skip=0&take=10

GET /umbraco/delivery/api/v2/content?sort=name:asc&sort=createDate:asc

Extension points

The Delivery API has been designed for extensibility, offering multiple extension points that provide greater flexibility and customization options. These extension points allow you to tailor the API's behavior and expand its capabilities to meet your specific requirements.

You can find detailed information about the specific areas of extension in the articles below:

• Tailor the API's response for custom property editors

• Extend the API with custom selecting, filtering, and sorting options

Handling deeply nested JSON output

.NET imposes a limit on the depth of object nesting within rendered JSON. This is done to detect cyclic references. Learn more about it in the official .NET API docs.

If the limit is exceeded, .NET will throw a JsonException.

The content models might be so deeply nested that the Delivery API produces JSON that exceeds this limit. If this happens, the JsonException will be logged and shown in the Umbraco log viewer.

To handle this we have to change the limit. Since the Delivery API has its own JSON configuration, we can do so without affecting the rest of our site.

1. Add the following using statements to Program.cs:

using Umbraco.Cms.Api.Common.DependencyInjection;
using Umbraco.Cms.Core;

1. Add the following code snippet to the Program.cs file:

builder.Services.AddControllers().AddJsonOptions(
    Constants.JsonOptionsNames.DeliveryApi,
    options =>
    {
        // set the maximum allowed depth of
        options.JsonSerializerOptions.MaxDepth = {desired max depth}
    });

Current Limitations

The Content Delivery API provides a powerful and flexible way to retrieve content from the Umbraco CMS. There are, however, certain limitations to be aware of.

In this section, we will discuss some of the known limitations of the API, and how to work around them if necessary.

Protected content

The Delivery API supports protected content and member authentication. This is an opt-in feature. You can read more about it in the Protected Content in the Delivery API article.

If member authentication is not explicitly enabled, protected content is ignored and never exposed by the Delivery API.

As a result, lifting protection from a content item requires an additional step to ensure it becomes accessible through the Delivery API. The recommended way is to publish the content item again. Alternatively, you can manually rebuild the DeliveryApiContentIndex to reflect the changes.

Property editors

Certain limitations are associated with some of the built-in property editors in Umbraco. These limitations are listed below.

Rich Text Editor

Internal links may be insufficient in a multi-site setup when outputting the Rich Text Editor content as HTML (the default format). There is a possibility that this limitation may be addressed in future updates. However, consider the alternative approach to rendering the Rich Text Editor content as JSON.

Member Picker

The Member Picker property editor is not supported in the Delivery API to avoid the risk of leaking member data.

Content Picker

The Content Picker property editor is not supported in the Delivery API when configured for Members. This is due to the concern of potentially leaking member data.

Making changes to DisallowedContentTypeAliases

When changing the content type aliases in the Umbraco:CMS:DeliveryApi:DisallowedContentTypeAliases configuration setting, DeliveryApiContentIndex should be rebuilt. This ensures that disallowed content types are not exposed through the Delivery API.

Alternatively, the relevant content items can be republished. This will ensure that changes are reflected, eliminating the need to rebuild the index.

The Delivery API allows you to retrieve multiple items by utilizing the /umbraco/delivery/api/v2/content endpoint. With the built-in query parameters, you have the flexibility to get any number of content nodes based on your needs. For a comprehensive list of supported query options, please refer to the section.

For the query endpoint, we have created a new Examine index (DeliveryApiContentIndex) that facilitates fast retrieval of the desired content. This index ensures quick indexing and searching of data, with the possibility for future extensions.

In this article, we'll explore creating custom selecting, filtering, and sorting options to enhance the querying capabilities of the Delivery API.

Query options

Let's take a look at an example of using the query endpoint with query parameters for fetch, filter, and sort. A request might look like this:

The placeholders in the example (xxx, yyy, etc.) represent the values that each query option evaluates in order to determine the suitable query handler.

The implementation of each querying option consists of a class for indexing the data into the DeliveryApiContentIndex and another one for handling the query. By implementing the IContentIndexHandler interface, you can control how your relevant data is indexed and made available for querying through our index. And you can customize the querying behaviour to suit your needs by implementing the ISelectorHandler, IFilterHandler, and ISortHandler interfaces.

In the following sections, we will explore the implementation details of creating custom querying functionality for the Delivery API.

Custom selector

Selectors handle the fetch part of a query.

To showcase how to build a custom selector, consider a site structure with a few blog posts. A post is linked to an author, which is another content item.

Authors can be marked as 'Featured' using a toggle, granting them additional visibility and recognition. We will use this marker as part of the indexing implementation for our selector option.

The following example demonstrates the implementation of an AuthorSelector, which allows you to customize the querying behaviour specifically for finding all featured authors. This class contains both indexing and querying responsibilities. However, keep in mind that it is generally recommended to separate these responsibilities into dedicated classes.

The AuthorSelector class implements the ISelectorHandler and IContentIndexHandler interfaces.

ISelectorHandler allows for handling the fetch value in API queries through the CanHandle() and BuildSelectorOption() methods.

• CanHandle() determines if the given fetch query corresponds to the "featuredAuthors" value.

• BuildSelectorOption() constructs the selector option to search for authors with a positive value (for example, "y") in a "featured" index field.

The GetFields() and GetFieldValues() methods each play a role in defining how the data should be indexed and made searchable.

• GetFields() defines the behaviour of fields that are added to the index. In this example, the "featured" field is added as a "raw" string for efficient and accurate searching.

• GetFieldValues() is responsible for retrieving the values of the defined index fields. In this case, the "featured" field of content items of type "author". It creates an IndexFieldValue with the appropriate field value ("y" for featured, "n" otherwise), which will be added to the index.

Since our custom query option modifies the index structure, we will need to rebuild the DeliveryApiContentIndex. You can find it by navigating to the "Examine Management" dashboard in the "Settings" section. Once rebuilt, we can make a request to the Delivery API query endpoint as follows:

Request

Response

Custom filter

Filters handle the filter part of a query.

Staying within the topic of blog posts and their authors, we will create a custom filter to find posts by specific author(s).

This filter allows specifying the desired author(s) by their key (Guid) in an author: filter option. Multiple authors can be included by listing their keys as comma-separated-values, like:

Request

The response will include the blog posts associated with the provided authors, enabling us to retrieve only the relevant results from the API.

Response

Our filter implementation follows a similar structure to the custom selector we discussed earlier. We continue to utilize the IContentIndexHandler interface, but this time we introduce the IFilterHandler. This combination gives us flexibility and control over the filtering behaviour.

The procedure remains the same - we store and query the author key in a new "authorId" field within the index. Consequently, we will need to rebuild the index to reflect the changes.

To illustrate the implementation, consider the following code example:

The principal difference from the selector is that the filter implements BuildFilterOption() instead of BuildSelectorOption(). Here, the filter performs an exact match for any specified Guid in the query. Efficiently, this makes the filter perform an OR operation against the index.

Since we need to perform an exact match, the index field (authorId) is once again defined as a "raw" string. Other options include "analyzed" and "sortable" strings. These support "contains" searches and alpha-numeric sorting, respectively.

Filter operators

When implementing a filter, you can use the following operators: Is, IsNot, Contains, DoesNotContain, GreaterThan, GreaterThanOrEqual, LessThan and LessThanOrEqual.

It is possible to pass multiple values to each operator, and these values will be treated inclusively as an or operator. For example, if tag1 and tag2 were passed into a filter using the Is operator, any document containing either tag1 or tag2 would return. The request for this might look like this:

If you require this functionality to be restrictive i.e. tag1 and tag2, then the current approach would be to chain the custom filter. The request would change to look more like this:

Custom sort

Finally, we can also add custom handling for the sort part of the query.

We'll add a custom sort handler that allows us to sort blog posts based on a custom "publishDate" Date Picker property. The implementation will allow for sorting the posts in ascending or descending order.

To demonstrate this, consider the following implementation example:

The implementation follows the same structure as the other examples, defined by the IContentIndexHandler and ISortHandler interfaces.

One point to highlight is that we store the "publishDate" value as a "date" field in the index, which allows for correct date sorting.

Once more, when adding fields to the index, we need to rebuild it to reflect the changes.

In the following example request, we also apply the author filter to retrieve only "blogpost" content nodes, which we know have the "publishDate" field.

Request

Response

In many cases the Delivery API output is stateless, and it is not absolutely necessary to push content updates immediately. In these cases the API can greatly benefit from using output caching.

Output caching is an opt-in feature in the Delivery API. It can be configured individually for both the Content and Media Delivery APIs. When enabled, API outputs are cached on the server for each unique request, and re-used until the cache expires.

Under the hood, the Delivery API utilizes the built-in output caching middleware in ASP.NET Core to handle the cache.

Why use output caching?

Output caching is primarily designed to increase performance. While the Delivery API is performant on its own, output caching takes the performance to another level.

Another aspect to consider is the overall server load. Uncached requests require much more processing time than cached requests. Especially for high traffic sites, even a short-lived output cache makes a significant difference in the server load. This might result in a lesser need to scale instances, and thus a greener footprint for the site.

However, output caching does come with a few trade-offs:

• The cache lives in memory by default. This means the site will consume additional memory to handle the cache.

• The cache does not expire automatically when content changes. Therefore, editors will experience increased publishing time when making changes to existing content.

When not to use output caching

Output caching can be a bad fit in some cases:

• If editors require immediate publishing of content updates (see above).

• When using personalization in the API output.

• If a custom property editor requires re-rendering for every request (for example if a property value converter outputs the current time).

Configuring output caching

Output caching must be explicitly enabled by configuration. To enable it, add the OutputCache section to the DeliveryApi configuration in appsettings.json:

{
    "Umbraco": {
        "CMS": {
            "DeliveryApi": {
                "Enabled": true,
                "OutputCache": {
                    "Enabled": true,
                    "ContentDuration": "00:15:00",
                    "MediaDuration": "01:00:00"
                }
            }
        }
    }
}

The output cache duration (time-to-live) can be configured for the Content and Media Delivery APIs. In the example above, content output is cached for 15 minutes while media output is cached for an hour.

Load balancing considerations

The default output caching mechanism is based on the individual server instance memory. When hosting in a load balanced environment, this likely will not work, as the memory cache isn't synchronized across instances.

Instead you'll need to use a distributed caching solution like Redis cache. Starting with .NET 8, Microsoft supports output caching with Redis cache as backing store. Read more here.

Additional considerations

While output caching is a great way to boost performance, it should never be used as a band-aid to solve poor uncached performance. The Delivery API is generally performant without caching.

If you experience performance issues while querying the Delivery API, your first step should be to diagnose and fix the root cause. This could be any number of things, like:

• Un-performant value converters.

• Overly complex queries.

• An inexpedient content architecture.

• ...or something else entirely.

Hiding such problems behind output caching should only ever be considered as a short-term solution. In the long run it will not be a sustainable fix.

Umbraco allows for restricting access to content. Using the "Public access" feature, specific content items can be protected and made accessible only for authorized members. The same is possible in the Delivery API.

By default, protected content is ignored by the Delivery API, and is never exposed through any API endpoints. However, by enabling member authorization in the Delivery API, protected content can be accessed by means of access tokens.

Member authorization

Member authentication and authorization in the Delivery API is performed using the OpenId Connect flow Authorization Code Flow + Proof Key of Code Exchange (PKCE). This is a complex authorization flow, and it is beyond the scope of this article to explain it. Many articles can be found online that explain the flow in detail.

Most programming languages have OpenId Connect client libraries to handle the complexity for us. AppAuth is a great example of such a library. In ASP.NET Core, OpenId Connect support is built into the framework.

Enabling member authorization

Member authorization is an opt-in feature of the Delivery API. To enable it, configure MemberAuthorization:AuthorizationCodeFlow in the DeliveryApi section of appsettings.json:

• Enabled must be true.

• One or more LoginRedirectUrls must be configured. These specify where the server is allowed to redirect the client after a successful authorization.

• Optionally one or more LogoutRedirectUrls must be configured. These specify where the server is allowed to redirect the client after successfully terminating a session.

  • These are only necessary if logout is implemented in the client.

{
    "Umbraco": {
        "CMS": {
            "DeliveryApi": {
                "Enabled": true,
                "MemberAuthorization": {
                    "AuthorizationCodeFlow": {
                        "Enabled": true,
                        "LoginRedirectUrls": [
                            "https://absolute.redirect.url/path/after/login"
                        ],
                        "LogoutRedirectUrls": [
                            "https://absolute.redirect.url/path/after/logout"
                        ]
                    }
                }
            }
        }
    }
}

Server endpoints

Many client libraries support automatic discovery of the server OpenId endpoints. This is also supported by the Delivery API, so likely we do not have to worry about the server endpoints.

If automatic discovery is not applicable, the server endpoints must be configured manually. The server endpoints can be found at https://{server-host}/.well-known/openid-configuration.

Client configuration

To connect the client and the server, we need to apply some configuration details to the connection:

• The client_id must be umbraco-member.

• The response_type must be code.

• The redirect_uri must be one of the configured LoginRedirectUrls.

• The scope must either be empty, or be openid and/or offline_access.

• PKCE must be enabled.

For inspiration, the samples section at the end of this article shows how to configure an ASP.NET Core client.

Logging in members

Authorization Code Flow + Proof Key of Code Exchange (PKCE) requires the authentication service (identity provider) to be separate from the client application. This is to ensure that credentials are never exposed directly to the client application.

As an authentication service, we can use both Umbraco's built-in member authentication and external identity providers. By default the Delivery API attempts to use the built-in member authentication.

How to use the built-in member authentication

First and foremost we need a login page. By ASP.NET Core defaults, this page should be located at /Account/Login. However, we can change the default path by adding the following piece of code:

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Identity;
using Microsoft.Extensions.Options;

namespace Umbraco.Samples;

public static class ConfigureCustomMemberLoginPathExtensions
{
    public static IUmbracoBuilder SetCustomMemberLoginPath(this IUmbracoBuilder builder)
    {
        builder.Services.ConfigureOptions<ConfigureCustomMemberLoginPath>();
        return builder;
    }

    private class ConfigureCustomMemberLoginPath : IConfigureNamedOptions<CookieAuthenticationOptions>
    {
        public void Configure(string? name, CookieAuthenticationOptions options)
        {
            if (name != IdentityConstants.ApplicationScheme)
            {
                return;
            }

            Configure(options);
        }

        // replace options.LoginPath with the path you want to use for default member logins
        public void Configure(CookieAuthenticationOptions options)
            => options.LoginPath = "/path/to/the-custom-login-page";
    }
}

To invoke this code, we need to call SetCustomMemberLoginPath() in Program.cs:

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    // add this line
    .SetCustomMemberLoginPath()
    .Build();

No matter the path to the login page, we still need a page to render the login screen. Create a content item located at the login page path, and use this template to render it:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using Umbraco.Cms.Web.Common.Models
@using Umbraco.Cms.Web.Website.Controllers
@using Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = null;
    var loginModel = new LoginModel
    {
        // important: we must set the redirect URL from the query string
        RedirectUrl = Context.Request.Query["ReturnUrl"]
    };
}
<html lang="en">
<head>
    <title>Login page</title>
</head>
<body>
@using (Html.BeginUmbracoForm<UmbLoginController>("HandleLogin", new { RedirectUrl = loginModel.RedirectUrl }))
{
    <h4>Log in with a local account.</h4>
    <hr />
    <div asp-validation-summary="ModelOnly" class="text-danger"></div>
    <div>
        <label asp-for="@loginModel.Username"></label>
        <input asp-for="@loginModel.Username" required />
        <span asp-validation-for="@loginModel.Username"></span>
    </div>
    <div>
        <label asp-for="@loginModel.Password"></label>
        <input asp-for="@loginModel.Password" required />
        <span asp-validation-for="@loginModel.Password"></span>
    </div>

    <button type="submit" class="btn btn-primary">Log in</button>
}
</body>
</html>

With all this in place, it's time to test the setup. Use a browser to perform a request to https://{server-host}/umbraco/delivery/api/v1/security/member/authorize with these query string parameters:

• client_id=umbraco-member

• redirect_uri=https://absolute.redirect.url/path/after/login (replace the value with one of the configured login redirect URLs)

• response_type=code

• code_challenge=WZRHGrsBESr8wYFZ9sx0tPURuZgG2lmzyvWpwXPKz8U

• code_challenge_method=S256

If everything works as expected, the request will yield a redirect to the login page. Completing the login form will cause a redirect to the specified redirect URL with a code query string parameter. The code can subsequently be exchanged for an access token, which can be used to access protected content.

For more inspiration on using the built-in member authentication, check the Members Registration and Login article. Here you will also learn how to create member sign-up functionality.

How to use external identity providers

Umbraco allows adding external identity providers for both backoffice users and members. The process is documented in detail in the External Login Providers article.

The Delivery API supports the same functionality. In the following we'll be using GitHub to test this.

First, we need to create an OAuth App in GitHub. This is done in the GitHub Developer Settings. Use https://{server-host}/umbraco/signin-github as authorization callback URL in the App.

Once the App is created, generate a new client secret within the App. Make sure to copy both the client ID of your App and the generated secret.

Now we need to connect Umbraco members with the App:

1. Add the NuGet package AspNet.Security.OAuth.GitHub to your Umbraco project.

2. Add the code below to configure the connection to the App. Remember to update the OAuth client ID and secret.

using Microsoft.Extensions.Options;
using Umbraco.Cms.Core;
using Umbraco.Cms.Web.Common.Security;

namespace Umbraco.Samples;

public static class GitHubAuthenticationExtensions
{
    private const string Scheme = "GitHub";

    public static IUmbracoBuilder AddGitHubAuthentication(this IUmbracoBuilder builder)
    {
        builder.Services.ConfigureOptions<GitHubMemberExternalLoginProviderOptions>();

        builder.AddMemberExternalLogins(logins =>
        {
            logins.AddMemberLogin(
                membersAuthenticationBuilder =>
                {
                    membersAuthenticationBuilder.AddGitHub(
                        membersAuthenticationBuilder.SchemeForMembers(Scheme),
                        options =>
                        {
                            // add your client ID and secret here
                            options.ClientId = "{OAuth App client ID}";
                            options.ClientSecret = "{OAuth App client secret}";
                            options.CallbackPath = "/umbraco/signin-github";
                            options.Scope.Add("user:email");
                            options.SaveTokens = true;
                        });
                });
        });

        return builder;
    }

    private class GitHubMemberExternalLoginProviderOptions : IConfigureNamedOptions<MemberExternalLoginProviderOptions>
    {
        public void Configure(string? name, MemberExternalLoginProviderOptions options)
        {
            if (name is not $"{Constants.Security.MemberExternalAuthenticationTypePrefix}{Scheme}")
            {
                return;
            }

            Configure(options);
        }

        public void Configure(MemberExternalLoginProviderOptions options)
            => options.AutoLinkOptions = new MemberExternalSignInAutoLinkOptions(
                autoLinkExternalAccount: true,
                defaultCulture: null,
                defaultIsApproved: true,
                defaultMemberTypeAlias: Constants.Security.DefaultMemberTypeAlias);
    }
}

Finally, we need to invoke the connection configuration by calling AddGitHubAuthentication() in Program.cs.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    // add this line
    .AddGitHubAuthentication()
    .Build();

Now we can test the setup. We'll be calling https://{server-host}/umbraco/delivery/api/v1/security/member/authorize as described previously, but we need to add one more query string parameter:

• identity_provider=UmbracoMembers.GitHub

If the setup is correct, the request will yield a redirect to the GitHub login page. Here we need to authorize the GitHub OAuth App we created earlier, in order to complete the login. Upon completion, a series of redirects will once more take us to the specified redirect URL with a code query string parameter.

Different client libraries have different ways of declaring the identity_provider in the authorization request. The samples section shows how to configure this in an ASP.NET Core client.

Combining built-in member authentication and external identity providers

We can also add the external identity providers to the member authentication login screen. This way the end user can decide whether to log in as a registered member, or use an external identity provider.

The Login partial view features an implementation of this combined login experience.

Accessing protected content

When the authorization flow completes we'll obtain an access token. This token can be used as a bearer token to access protected content for the logged-in member:

GET /umbraco/delivery/api/v2/content/{query}
Authentication: Bearer {access token}

Access tokens expire after one hour. Once expired, a new access token must be obtained to continue accessing protected content.

Refresh tokens

Refresh tokens provide a means to obtain a new access token without having to go through the authentication flow. A refresh token is issued automatically by the Delivery API when the offline_access scope is specified in the authorization request.

Logging out members

The member authorization is tied to the access and refresh tokens obtained in the authorization flow. Discarding these tokens efficiently terminates the access to protected content.

However, the tokens are still valid and can be reapplied until they expire. Depending on your scenario, it might be prudent to revoke the tokens and maybe even terminate the session on the server.

Revoking tokens

Access and refresh tokens can be revoked by performing a POST request containing the token:

POST /umbraco/delivery/api/v1/security/member/revoke
     client_id=umbraco-member
     token={token to revoke}
Content-Type: application/x-www-form-urlencoded

Terminating a session

When terminating a session on the server, the member is logged out of Umbraco. This means any subsequent authorization attempt will require an explicit login.

To terminate the active session for any given member, you must redirect the browser to the signout endpoint. The request must contain one of the white-listed LogoutRedirectUrls from the appsettings.json:

GET /umbraco/delivery/api/v1/security/member/signout?post_logout_redirect_uri={valid URL from LogoutRedirectUrls}

Testing with Swagger

The Delivery API Swagger document can be configured to support member authentication.

Before we can do that, we need two things in place:

1. We have to implement a login page as described above.

2. We must add https://{server-host}/umbraco/swagger/oauth2-redirect.html to the configured LoginRedirectUrls.

With these in place, we can enable member authentication in Swagger for the Delivery API by adding the following to Program.cs:

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

builder.Services.ConfigureOptions<Umbraco.Cms.Api.Delivery.Configuration.ConfigureUmbracoMemberAuthenticationDeliveryApiSwaggerGenOptions>();

The Swagger UI will now feature authorization.

Client configuration samples

The following samples show how to configure an ASP.NET Core client to utilize member authorization in the Delivery API.

To put these samples into context, please refer to the article above.

Basic client configuration

builder.Services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = "cookie";
        options.DefaultSignInScheme = "cookie";
        options.DefaultChallengeScheme = "oidc";
    })
    .AddCookie("cookie")
    .AddOpenIdConnect("oidc", options =>
    {
        // the Umbraco site is the "authority" (also referred to as "issuer")
        options.Authority = "https://{server-host}";

        // set the "client_id" parameter
        options.ClientId = "umbraco-member";

        // set the "response_type" parameter
        options.ResponseType = "code";

        // set the "redirect_uri" parameter (will be converted to an absolute URL by the framework)
        options.CallbackPath = "/signin-oidc";

        // set the "scope" parameter (remove the default scopes and only use the "openid" scope)
        options.Scope.Clear();
        options.Scope.Add("openid");

        // enable PKCE
        options.UsePkce = true;

        // use a form POST as response mode
        options.ResponseMode = "form_post";
    });

Using a named identity provider

builder.Services.AddAuthentication(...)
    .AddOpenIdConnect("oidc", options =>
    {
        // ...

        // set the "identity_provider" parameter
        options.Events.OnRedirectToIdentityProvider = context =>
        {
            context.ProtocolMessage.IdentityProvider = "UmbracoMembers.GitHub";
            return Task.CompletedTask;
        };
    });

Limitations

When using external identity providers, Umbraco still allows for performing local two-factor authentication for members. This feature is not available in the Delivery API. Instead, two-factor authentication should be performed at the identity provider.

Out of the box, the Delivery API supports custom property editors, ensuring they are rendered alongside the built-in ones in Umbraco. However, if the output generated by your property editor isn't optimal for a headless context, you have the ability to customize the API response. This customization won't impact the Razor rendering, allowing you to tailor the Content Delivery API response according to your specific requirements.

In this article, we'll look into how you can work with the IDeliveryApiPropertyValueConverter interface and implement custom property expansion for your custom property editors.

Prerequisite

The examples in this article revolve around the fictional My.Custom.Picker property editor. This property editor stores the key of a single content item and is backed by a property value converter.

We will not dive into the details of creating a custom property editor for Umbraco in this article. If you need guidance on that, please refer to the Creating a Property Editor and Property Value Converters articles.

Implementation

To customize the output of a property value editor in the Delivery API, we need to opt-in by implementing the IDeliveryApiPropertyValueConverter interface.

The code example below showcases the implementation of this interface in the property value converter for My.Custom.Picker. Our focus will be on the methods provided by the IDeliveryApiPropertyValueConverter, as they are responsible for customizing the Delivery API response.

Towards the end of the example, you will find the response models that we will be using.

The IsConverter() and GetPropertyValueType() methods are inherited from the PropertyValueConverterBase class, which is covered in the Property Value Converters article.

using Umbraco.Cms.Core.DeliveryApi;
using Umbraco.Cms.Core.Models.DeliveryApi;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.DeliveryApi;
using Umbraco.Cms.Core.PublishedCache;

namespace Umbraco.Docs.Samples;

public class MyCustomPickerValueConverter : PropertyValueConverterBase, IDeliveryApiPropertyValueConverter
{
    private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
    private readonly IApiContentRouteBuilder _apiContentRouteBuilder;

    public MyCustomPickerValueConverter(
        IPublishedSnapshotAccessor publishedSnapshotAccessor,
        IApiContentRouteBuilder apiContentRouteBuilder)
    {
        _publishedSnapshotAccessor = publishedSnapshotAccessor;
        _apiContentRouteBuilder = apiContentRouteBuilder;
    }

    public override bool IsConverter(IPublishedPropertyType propertyType)
        => propertyType.EditorAlias.Equals("My.Custom.Picker");

    public override Type GetPropertyValueType(IPublishedPropertyType propertyType)
        => typeof(Guid?);

    public PropertyCacheLevel GetDeliveryApiPropertyCacheLevel(IPublishedPropertyType propertyType)
        => PropertyCacheLevel.Elements;

    public PropertyCacheLevel GetDeliveryApiPropertyCacheLevelForExpansion(IPublishedPropertyType propertyType)
        => PropertyCacheLevel.Snapshot;

    public Type GetDeliveryApiPropertyValueType(IPublishedPropertyType propertyType)
        => typeof(DeliveryApiCustomPicker);

    public object? ConvertIntermediateToDeliveryApiObject(
        IPublishedElement owner,
        IPublishedPropertyType propertyType,
        PropertyCacheLevel referenceCacheLevel,
        object? inter,
        bool preview,
        bool expanding)
    {
        if (inter is null)
        {
            return null;
        }

        return BuildDeliveryApiCustomPicker(inter, expanding);
    }

    private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
    {
        if (!_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
            publishedSnapshot?.Content is null)
        {
            return null;
        }

        if (!Guid.TryParse(inter as string, out Guid id))
        {
            return null;
        }

        return new DeliveryApiCustomPicker { Id = id };
    }
}

public class DeliveryApiCustomPicker
{
    public Guid Id { get; set; }

    public DeliveryApiItemDetails? ItemDetails { get; set; }
}

public class DeliveryApiItemDetails
{
    public string? Name { get; set; }

    public IApiContentRoute? Route { get; set; }
}

The Implementation of the IDeliveryApiPropertyValueConverter interface can be found in the following methods:

• GetDeliveryApiPropertyCacheLevel(): This method specifies the cache level used for our property representation in the Delivery API response.

• GetDeliveryApiPropertyCacheLevelForExpansion(): This method specifies the cache level used for our property representation in the Delivery API response when property expansion is applied.

• GetDeliveryApiPropertyValueType(): This method defines the value type of the custom property output for the Delivery API response.

• ConvertIntermediateToDeliveryApiObject(): This method converts the value from the property editor to the desired custom object in a headless context.

In the given example, the content key (Guid value) is used when rendering with Razor. This is sufficient because Razor provides full access to the published content within the rendering context. In a headless context, we do not have the same access. To prevent subsequent round-trips to the server, we create a richer output model specifically for the Delivery API.

The following example request shows how our custom implementation is reflected in the resulting API response. In this case, our custom property editor is configured under the alias "pickedItem".

Request

GET /umbraco/delivery/api/v2/content/item/blog

Response

{
    "name": "Blog",
    "createDate": "2023-05-25T11:26:52.591927",
    "updateDate": "2023-06-07T12:53:41.339963",
    "route": {
        "path": "/",
        "startItem": {
            "id": "88694917-ac4a-4cfa-aa82-d89a81940126",
            "path": "blog"
        }
    },
    "id": "88694917-ac4a-4cfa-aa82-d89a81940126",
    "contentType": "blog",
    "properties": {
        "pickedItem": {
            "id": "61df413c-02b2-480d-8cb5-8e3c35132838",
            "itemDetails": null
        }
    },
    "cultures": {}
}

Property expansion support

Property expansion allows us to conditionally add another level of detail to the Delivery API output. Usually, these additional details are "expensive" to retrieve (for example, requiring database access to populate). By applying property expansion, we provide the option for the caller of the API to opt-in explicitly to this "expensive" operation. From the caller's perspective, the alternative might be an even more expensive additional round-trip to the server.

In our example, property expansion is implemented within ConvertIntermediateToDeliveryApiObject(). By considering the value of the expanding parameter, we can modify the BuildDeliveryApiCustomPicker() method as follows:

private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
{
    if (!_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
        publishedSnapshot?.Content is null)
    {
        return null;
    }

    if (!Guid.TryParse(inter as string, out Guid id))
    {
        return null;
    }

    // Property expansion support
    if (expanding == false)
    {
        return new DeliveryApiCustomPicker { Id = id };
    }

    IPublishedContent? content = publishedSnapshot.Content.GetById(id);
    if (content is null)
    {
        return new DeliveryApiCustomPicker { Id = id };
    }

    IApiContentRoute? route = _apiContentRouteBuilder.Build(content);
    var itemDetails = new DeliveryApiItemDetails { Name = content.Name, Route = route };

    return new DeliveryApiCustomPicker { Id = id, ItemDetails = itemDetails };
}

If the expanding parameter is false, the method returns the same shallow representation of the referenced content item as before. Otherwise, we retrieve the corresponding IPublishedContent and construct our response object accordingly.

To see the expanded output in the API response, we need to add the expand query parameter to our request. We can use either ?expand=properties[$all] to expand all properties or ?expand=properties[pickedItem] to expand the specific 'pickedItem' property.

Request

GET /umbraco/delivery/api/v2/content/item/blog?expand=properties[pickedItem]

Response

{
    "name": "Blog",
    "createDate": "2023-05-25T11:26:52.591927",
    "updateDate": "2023-06-07T12:53:41.339963",
    "route": {
        "path": "/",
        "startItem": {
            "id": "88694917-ac4a-4cfa-aa82-d89a81940126",
            "path": "blog"
        }
    },
    "id": "88694917-ac4a-4cfa-aa82-d89a81940126",
    "contentType": "blog",
    "properties": {
        "pickedItem": {
            "id": "61df413c-02b2-480d-8cb5-8e3c35132838",
            "itemDetails": {
                "name": "Codegarden",
                "createDate": "2023-05-21T00:34:11.513868",
                "updateDate": "2023-06-06T17:46:12.833186",
                "route": {
                    "path": "/codegarden/",
                    "startItem": {
                        "id": "88694917-ac4a-4cfa-aa82-d89a81940126",
                        "path": "blog"
                    }
                }
            }
        }
    },
    "cultures": {}
}

The itemDetails property of the pickedItem in the JSON response contains the additional details of the selected content item.

Property expansion and limiting applies only to select property editors. The following built-in property editors in Umbraco support expansion and limiting:

• Picker editors

  • Content Picker

  • Media Picker

  • Media Picker (legacy)

  • Multinode Treepicker

• Block-based editors

  • Block List

  • Block Grid

  • Rich Text Editor (with blocks)

Working with picker editors

In the following examples, we will be querying a content tree with blog posts and blog authors:

• All blog posts are located under a root content item called "Posts".

• All authors are located under a root content item called "Authors".

The blog post content type (post) contains two properties that support expansion and limiting:

• author: A content picker for picking the author of the post.

• coverImage: A media picker for picking an image for the post.

The author content type (author) contains a single property that supports expansion and limiting:

• picture: A media picker for picking a picture of the author.

When fetching a blog post, the author and coverImage properties are returned in their un-expanded representation by default. This representation does not contain any property data; the properties collections of author and coverImage are empty:

Request

GET /umbraco/delivery/api/v2/content/item/set-your-content-free/
Start-Item: posts

Response

{
    "contentType": "post",
    "name": "Set your content free",
    "createDate": "2023-08-14T08:35:58.8397754",
    "updateDate": "2023-08-14T08:54:41.8018872",
    "route": {
        "path": "/set-your-content-free/",
        "startItem": {
            "id": "d88fefc3-da04-493d-9533-294a7264b27f",
            "path": "posts"
        }
    },
    "id": "5de65f2e-055e-4e6a-adc3-edb340dcd2e8",
    "properties": {
        "author": {
            "contentType": "author",
            "name": "Go Fish",
            "createDate": "2023-08-14T08:35:58.9245488",
            "updateDate": "2023-11-06T14:21:22.2160133",
            "route": {
                "path": "/go-fish/",
                "startItem": {
                    "id": "a0e500e2-295e-43e0-ab85-71a44e690c31",
                    "path": "authors"
                }
            },
            "id": "f5baeee9-fe8d-4e54-b5c8-fc0373df61cf",
            "properties": {}
        },
        "coverImage": [
            {
                "focalPoint": null,
                "crops": [],
                "id": "dbb62958-de31-465f-bdbe-5e9079b54b25",
                "name": "Arrows",
                "mediaType": "Image",
                "url": "/media/lyulnwzr/arrows.png",
                "extension": "png",
                "width": 1080,
                "height": 530,
                "bytes": 24069,
                "properties": {}
            }
        ],
        "excerpt": "Fusce ut mauris ornare, mollis felis ac, convallis neque. Aenean eu tortor ac dui dictum lacinia. Aliquam erat volutpat. Sed malesuada congue imperdiet. Sed dictum aliquam velit. Nunc non nibh dignissim, consequat quam ac, mattis turpis. ",
        "content": {
            "markup": "<p>Maecenas consectetur tellus ut aliquet gravida. Mauris at tortor et tellus ultrices tempor vitae nec sapien. Etiam in luctus justo. Praesent rutrum turpis nec maximus congue. Sed sed convallis dui, ut luctus magna. Cras eget diam et sem consequat dictum ut in diam.</p>\n<p>Donec feugiat, quam ut varius ultricies, erat purus luctus ex, at sagittis tellus ante vel orci. Nunc dapibus purus feugiat, rhoncus est non, feugiat metus. Vivamus vulputate mauris id urna ultrices sagittis non ut est. Mauris mauris diam, interdum nec lectus et, vehicula faucibus risus. Etiam varius sem erat, nec venenatis elit pellentesque sed. Interdum et malesuada fames ac ante ipsum primis in faucibus.</p>\n<p>Sed nibh arcu, feugiat eu arcu sed, posuere lacinia urna. Phasellus interdum euismod sagittis. Etiam vel erat sed erat posuere placerat. Sed pulvinar tincidunt suscipit.</p>\n<p>Curabitur molestie turpis elit, vitae bibendum mi convallis a. Etiam convallis, massa vitae sagittis consectetur, lacus odio condimentum felis, ac congue ligula odio eu tortor. Proin dignissim sit amet eros non lobortis. Sed blandit dolor id magna pulvinar auctor. Maecenas sed mi vel arcu pretium sodales in quis urna. Nunc lectus nunc, posuere efficitur dignissim congue, mollis at orci.</p>",
            "blocks": []
        },
        "tags": [
            "Content",
            "Awesome"
        ]
    },
    "cultures": {}
}

If we want to show the author's picture when rendering the blog post, we need to expand the author property. By expanding the property, the author properties (including picture) are included in the output. We can achieve this by appending the expand parameter to our request.

The expand parameter syntax is as follows:

expand=properties[propertyAlias1,propertyAlias2,propertyAlias3]

Within the properties part of the expand parameter we can list the aliases of the properties we wish to expand. If we want to expand all expandable properties, we can use the operator $all instead:

expand=properties[$all]

Request

GET /umbraco/delivery/api/v2/content/item/set-your-content-free/
    ?expand=properties[author]
Start-Item: posts

Response

{
    "contentType": "post",
    "name": "Set your content free",
    "createDate": "2023-08-14T08:35:58.8397754",
    "updateDate": "2023-08-14T08:54:41.8018872",
    "route": {
        "path": "/set-your-content-free/",
        "startItem": {
            "id": "d88fefc3-da04-493d-9533-294a7264b27f",
            "path": "posts"
        }
    },
    "id": "5de65f2e-055e-4e6a-adc3-edb340dcd2e8",
    "properties": {
        "author": {
            "contentType": "author",
            "name": "Go Fish",
            "createDate": "2023-08-14T08:35:58.9245488",
            "updateDate": "2023-11-06T14:21:22.2160133",
            "route": {
                "path": "/go-fish/",
                "startItem": {
                    "id": "a0e500e2-295e-43e0-ab85-71a44e690c31",
                    "path": "authors"
                }
            },
            "id": "f5baeee9-fe8d-4e54-b5c8-fc0373df61cf",
            "properties": {
                "picture": [
                    {
                        "focalPoint": null,
                        "crops": [],
                        "id": "598c8ce5-1323-4926-98a4-0f3a395dae2d",
                        "name": "Fishtank",
                        "mediaType": "Image",
                        "url": "/media/2ogiywjd/fishtank.png",
                        "extension": "png",
                        "width": 1080,
                        "height": 1080,
                        "bytes": 26941,
                        "properties": {}
                    }
                ],
                "biography": "Cras fermentum enim vitae varius tristique. Suspendisse tempor quis lacus vitae facilisis. Ut eget mauris tempus dui pulvinar egestas vel eget nibh.\n\nDonec hendrerit sem eu diam sodales luctus non sed urna. Ut sapien ex, imperdiet non eleifend nec, venenatis et purus. Integer tincidunt cursus cursus.\n\nSuspendisse euismod sem nisi, aliquam dignissim sem dictum non. Ut et ex lacus. Fusce ac nisi mattis, ultrices nibh ac, facilisis leo. Aliquam faucibus, elit eu posuere scelerisque, mi enim accumsan lorem, quis rhoncus libero massa quis ligula.",
                "dateOfBirth": "1996-04-04T00:00:00Z"
            }
        },
        "coverImage": [
            {
                "focalPoint": null,
                "crops": [],
                "id": "dbb62958-de31-465f-bdbe-5e9079b54b25",
                "name": "Arrows",
                "mediaType": "Image",
                "url": "/media/lyulnwzr/arrows.png",
                "extension": "png",
                "width": 1080,
                "height": 530,
                "bytes": 24069,
                "properties": {}
            }
        ],
        "excerpt": "Fusce ut mauris ornare, mollis felis ac, convallis neque. Aenean eu tortor ac dui dictum lacinia. Aliquam erat volutpat. Sed malesuada congue imperdiet. Sed dictum aliquam velit. Nunc non nibh dignissim, consequat quam ac, mattis turpis. ",
        "content": {
            "markup": "<p>Maecenas consectetur tellus ut aliquet gravida. Mauris at tortor et tellus ultrices tempor vitae nec sapien. Etiam in luctus justo. Praesent rutrum turpis nec maximus congue. Sed sed convallis dui, ut luctus magna. Cras eget diam et sem consequat dictum ut in diam.</p>\n<p>Donec feugiat, quam ut varius ultricies, erat purus luctus ex, at sagittis tellus ante vel orci. Nunc dapibus purus feugiat, rhoncus est non, feugiat metus. Vivamus vulputate mauris id urna ultrices sagittis non ut est. Mauris mauris diam, interdum nec lectus et, vehicula faucibus risus. Etiam varius sem erat, nec venenatis elit pellentesque sed. Interdum et malesuada fames ac ante ipsum primis in faucibus.</p>\n<p>Sed nibh arcu, feugiat eu arcu sed, posuere lacinia urna. Phasellus interdum euismod sagittis. Etiam vel erat sed erat posuere placerat. Sed pulvinar tincidunt suscipit.</p>\n<p>Curabitur molestie turpis elit, vitae bibendum mi convallis a. Etiam convallis, massa vitae sagittis consectetur, lacus odio condimentum felis, ac congue ligula odio eu tortor. Proin dignissim sit amet eros non lobortis. Sed blandit dolor id magna pulvinar auctor. Maecenas sed mi vel arcu pretium sodales in quis urna. Nunc lectus nunc, posuere efficitur dignissim congue, mollis at orci.</p>\n<p>Aenean elit arcu, cursus sit amet vulputate eu, dignissim sit amet lorem. Nunc tempus rhoncus lorem, sit amet finibus mi scelerisque sollicitudin. Pellentesque auctor, nunc facilisis molestie ullamcorper, justo magna pellentesque dui, vel posuere est massa eget nibh. Sed dignissim eget purus vitae malesuada. Maecenas eu ultricies nunc. Sed porta pretium ligula, non auctor arcu blandit elementum. Nullam nibh metus, consequat non imperdiet et, scelerisque id urna. Vivamus mollis, dolor ac fringilla bibendum, leo turpis finibus libero, sit amet porttitor nunc magna non diam.</p>\n<p>Curabitur cursus ullamcorper mauris. Fusce porta turpis at metus fermentum, commodo rhoncus leo dignissim. Etiam eu eleifend elit, sit amet pulvinar nibh. In pharetra massa massa, sit amet convallis leo consectetur vitae. In id pharetra sapien, sit amet tincidunt enim.</p>\n<p>Duis velit lectus, mollis eu eros sed, dignissim scelerisque neque. Mauris blandit sit amet diam dignissim cursus.</p>\n<p>Integer ornare ultrices finibus. Nullam iaculis eget sapien in porttitor. Etiam sit amet viverra mauris. Vestibulum risus ligula, placerat eget tortor vel, mattis porta odio. Vestibulum non euismod lacus. Integer quis velit suscipit, commodo mi sed, rutrum metus. Donec auctor ex ut elit vehicula, quis tincidunt odio laoreet. Suspendisse pharetra sit amet ante quis consequat. Duis finibus pellentesque urna ac molestie.</p>",
            "blocks": []
        },
        "tags": [
            "Content",
            "Awesome"
        ]
    },
    "cultures": {}
}