Blog / Development

Calling the Umbraco Management API from outside the backoffice

Published
Reading time
14 minutes
Category
Development
On this page 11 sections
  1. Start
  2. What the Management API is, and what it replaced
  3. Exploring endpoints with Swagger first
  4. API users instead of shared admin accounts
  5. Getting a token and calling an endpoint
  6. Token lifetime is where real integrations go wrong
  7. Scoping the API user
  8. Writing your own Management API endpoints
  9. What to watch for
  10. When I would reach for it
  11. Frequently asked questions
  12. Further reading
Calling The Umbraco Management API From Outside The Backoffice
Most Umbraco integrations I come across only ever talk to the Delivery API, or to Umbraco's services from inside the application. The Management API gets far less attention, which is a pity, because it is the same API the backoffice itself uses to talk to the server. Anything an editor or administrator can do in the backoffice has an endpoint behind it, and Umbraco lets external applications call those endpoints too, without anyone logging into the backoffice.
That opens up a useful category of work: scheduled jobs, deployment tooling, synchronisation with other systems and bulk operations that nobody wants to click through by hand. It also raises the questions you would ask about any machine-to-machine integration. Who is calling, with which permissions, and what happens when the credentials leak or the token expires? This post walks through how access works (API users and the client credentials flow), how to build a client that does not hammer your database with tokens, and where custom endpoints fit in.

What the Management API is, and what it replaced

According to the Umbraco documentation, the Management API is a replacement for the old backoffice controllers, which lacked RESTful capabilities. It is built into Umbraco, documented with OpenAPI, and it is what the backoffice uses to communicate with the backend.
That last part is the interesting one. Because the backoffice is just another client of this API, the endpoints are not a cut-down subset exposed for third parties. If you have been around since the days of UmbracoAuthorizedApiController, this is the successor to that pattern. A community write-up on upgrading from Umbraco 13 to 16 points out that both UmbracoApiController and UmbracoAuthorizedApiController no longer exist in Umbraco 16, and that custom endpoints for backoffice extensions now belong in the Management API. So even if you never call it from the outside, you may well end up writing controllers for it.

Exploring endpoints with Swagger first

Umbraco ships with OpenAPI documentation for both the Management API and the Content Delivery API. You pick the definition you want, press Authorize, and can try endpoints directly from the browser. The documentation walks through this with the Audit Log endpoints as an example, which is a harmless place to start.
Which OAuth client you can use depends on the environment. In production, only the umbraco-back-office client is allowed to connect to the Management API. In non-production environments the umbraco-swagger and umbraco-postman clients can be used as well. There is also a documented Postman setup that builds on this. In practice you can explore freely on a local or staging site, but you should not plan on the Swagger or Postman clients being available as a test bench in production, and you should not build anything that depends on them there.

API users instead of shared admin accounts

The old habit for machine access is to create a regular user, give it a long password and hope nobody uses it to log in. Umbraco has a proper alternative: the API user.
An API user is identical to a regular user with one exception. It has no password, and it cannot log into the backoffice. Since it is otherwise a normal user, you control what it may do with the same user groups and permissions you already use for editors. You create one in the Users section via Create and then API User, enter a name and email, pick a user group and create the user.
Client IDs for API users are prefixed with umbraco-back-office-. The documentation explains that the prefix guards against an API user accidentally taking over one of the client IDs Umbraco uses itself. When you set up client credentials you therefore end up with something like umbraco-back-office-my-client.

Getting a token and calling an endpoint

External consumers must use the OpenID Connect client credentials flow. You post the client ID and secret to the token endpoint at /umbraco/management/api/v1/security/back-office/token and receive a bearer token. The documentation shows a response with token_type set to Bearer and an expires_in of 299 seconds. The following is adapted from the sample in the Umbraco documentation. It uses the Duende.IdentityModel NuGet package and calls the "current user" endpoint:
using System.Net.Http.Json;
using Duende.IdentityModel.Client;

const string host = "https://localhost:44391";

var client = new HttpClient();

var tokenResponse = await client.RequestClientCredentialsTokenAsync(
    new ClientCredentialsTokenRequest
    {
        Address = $"{host}/umbraco/management/api/v1/security/back-office/token",
        ClientId = "umbraco-back-office-my-client",
        ClientSecret = "my-client-secret"
    }
);

if (tokenResponse.IsError || tokenResponse.AccessToken is null)
{
    Console.WriteLine($"Error obtaining a token: {tokenResponse.ErrorDescription}");
    return;
}

client.SetBearerToken(tokenResponse.AccessToken);

var apiResponse = await client.GetAsync($"{host}/umbraco/management/api/v1/user/current");
var apiUser = await apiResponse
    .EnsureSuccessStatusCode()
    .Content
    .ReadFromJsonAsync<ApiUserResponse>();

Console.WriteLine($"Hello, {apiUser?.Name} ({apiUser?.Email})");

public class ApiUserResponse
{
    public required Guid Id { get; set; }
    public required string Name { get; set; }
    public required string Email { get; set; }
}
I have not run this myself, so treat it as the documented sample rather than something I have verified. The shape of the flow is what matters: one request for a token, then ordinary HttpClient calls with the bearer header set. Note that the Management API does not support OpenID Connect Discovery (the docs say that is reserved for members accessing protected content through the Delivery API), so a generic OIDC library that expects a discovery document needs the token endpoint configured by hand.

Token lifetime is where real integrations go wrong

A console sample requests a token once and exits, so it never runs into the problem a real integration has. The documentation says explicitly that you can keep issuing new tokens for the same credentials, but that you should reuse a token within its lifespan, both for performance and to avoid flooding the Umbraco database with tokens. With a lifetime in the order of five minutes, a worker that calls the API a few times per second will create a lot of tokens if it asks for a new one on every call.
The documentation does not prescribe how to do the reuse, so what follows is my own approach. I would put token retrieval behind a small service that caches the token for slightly less than its lifetime. This sketch builds on the same Duende call as the sample above and has not been tested against a running site:
using Duende.IdentityModel.Client;
using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Options;

public class ManagementApiOptions
{
    public required string Host { get; set; }
    public required string ClientId { get; set; }
    public required string ClientSecret { get; set; }
}

public class ManagementApiTokenProvider(
    HttpClient httpClient,
    IMemoryCache cache,
    IOptions<ManagementApiOptions> options)
{
    private const string CacheKey = "umbraco-management-api-token";

    public async Task<string> GetTokenAsync(CancellationToken cancellationToken = default)
    {
        if (cache.TryGetValue(CacheKey, out string? cached) && cached is not null)
        {
            return cached;
        }

        var settings = options.Value;
        var response = await httpClient.RequestClientCredentialsTokenAsync(
            new ClientCredentialsTokenRequest
            {
                Address = $"{settings.Host}/umbraco/management/api/v1/security/back-office/token",
                ClientId = settings.ClientId,
                ClientSecret = settings.ClientSecret
            },
            cancellationToken);

        if (response.IsError || response.AccessToken is null)
        {
            throw new InvalidOperationException(
                $"Could not obtain a Management API token: {response.ErrorDescription}");
        }

        // Expire the cache entry a little early so we never send a token that is about to lapse.
        var lifetime = TimeSpan.FromSeconds(Math.Max(response.ExpiresIn - 30, 1));
        cache.Set(CacheKey, response.AccessToken, lifetime);

        return response.AccessToken;
    }
}
Two details are worth pointing out. The 30 second safety margin matters because the token in the documentation only lives for 299 seconds, and a request that starts just before expiry can still be rejected. And if several callers hit this at the same moment on a cold cache, they will each request a token. For most integrations that is acceptable, but if yours is chatty on startup, guard the fetch with a SemaphoreSlim. Bind ManagementApiOptions from configuration and keep the secret in your secret store rather than in appsettings.json.

Scoping the API user

Because an API user lives in a user group, the group is your authorisation boundary. An integration that only needs to read audit logs or manage a handful of content nodes does not need administrator rights, and granting them because it was quicker is the kind of shortcut that turns into an incident later.
My approach would be one API user per consumer, each in a user group with the narrowest permissions that make the integration work. A single shared API user for every script is convenient until one of those scripts needs to be switched off, or one secret needs rotating, and suddenly everything has to change at once. Separate users also make it easier to see in the audit trail which integration did what, although I would verify what the audit log actually records for API users in your own setup before relying on that.

Writing your own Management API endpoints

The Management API is also where custom backoffice endpoints live. The documentation's tutorial for creating a backoffice API starts from a controller that inherits ManagementApiControllerBase, with a route attribute and an API explorer group name so the endpoints show up as their own section in the OpenAPI documentation:
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Common.Attributes;
using Umbraco.Cms.Api.Management.Controllers;
using Umbraco.Cms.Api.Management.Routing;

namespace UmbracoDocs.Samples;

[VersionedApiBackOfficeRoute("my/item")]
[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase
{
}
From there the tutorial adds regular actions (HttpGet, create, update and delete) with skip and take parameters for paging. The docs describe ManagementApiControllerBase as the foundation that provides the functionality needed to manage APIs within the backoffice environment. A forum discussion about Umbraco 17 describes it as an abstract controller that mainly stacks the attributes that make an endpoint part of the Management API, including a backoffice authorisation policy. That is a community explanation rather than documentation, so check the source before building on it, but it explains why these endpoints are protected the same way as the built-in ones.
One practical note: the tutorial and the main Management API page do not agree on where the documentation is served. The current tutorial refers to /umbraco/openapi/, while the older Umbraco 14 version of the same tutorial refers to /umbraco/swagger/. If you are following documentation for a specific version, check the path against the version you are actually running.

What to watch for

  • Backoffice client authentication changed in Umbraco 17. The 17 upgrade notes say the backoffice client's authentication against the Management API was tightened, following a draft IETF RFC for browser-based apps. API user authentication and the Delivery API are unaffected, but custom backoffice extensions that talk to the Management API might be. If you maintain such extensions, read the version-specific upgrade notes before upgrading.
  • Swagger and Postman clients are for non-production. Production only accepts the umbraco-back-office client for backoffice use, plus your own API user clients for external access.
  • Token reuse is your responsibility. Nothing stops a naive client from requesting a token per call. The cost shows up in the database, not in your code.
  • Treat the client secret like any other credential. It grants whatever the user group allows, so keep it out of source control and rotate it when people leave a project.

When I would reach for it

For read-only delivery of published content to a frontend, the Content Delivery API is still the obvious choice. The Management API is for the other direction: automating things that editors or administrators would otherwise do by hand, such as bulk operations, synchronisation with an external system or tooling around deployments. API users, client credentials and normal user group permissions mean those integrations can be given exactly the access they need and nothing more. For me that is the strongest argument for using it instead of building yet another custom endpoint with its own authentication story.
If you do need something the built-in endpoints do not cover, adding your own controller to the Management API keeps it in the same documentation, behind the same authorisation, and consistent with how the backoffice itself is built. That consistency is worth more than the few lines you save by writing a standalone minimal API.

Frequently asked questions

What is the Umbraco Management API?

It is the API built into Umbraco that the backoffice uses to communicate with the backend. It replaces the older backoffice controllers that lacked RESTful capabilities, and it can also be used for integrations between Umbraco and external systems.

How do I authenticate against the Management API from an external application?

Create an API user in the Users section, use its client ID and secret with the OpenID Connect client credentials flow against /umbraco/management/api/v1/security/back-office/token, and send the returned access token as a bearer token.

Can an API user log into the backoffice?

No. An API user is a regular user without a password and is not allowed to log into the backoffice. Its permissions are controlled through user groups, like any other user.

Should I request a new token for every call?

No. Access tokens have a fixed expiry, and the documentation recommends reusing a token within its lifespan to improve performance and avoid filling the database with tokens.

Further reading

The Management API, External Access and API Users pages in the official Umbraco documentation, and the "Creating a backoffice API" tutorial for custom endpoints.

Comments

No comments yet

Spotted a mistake, or solved this differently? Add the first comment below.

Leave a comment

Comment
Comments are moderated. Be kind, be friendly, be specific.