The Management API can be used directly for integrations between Umbraco and external systems.

When consuming the Management API from an external source, you must use the OpenId Connect Client Credentials flow for authorization. Refer to the API Users article for details on setting up Client Credentials.

With a set of Client Credentials in place, you can obtain an access token from the Management API token endpoint: /umbraco/management/api/v1/security/back-office/token.

The token endpoint response looks like this:

{
  "access_token": "ZnEAKg5YwDc7621y6xZlEdT9kwp_ULGQPc5mnY9cDw0",
  "token_type": "Bearer",
  "expires_in": 299
}

As shown, the access token should be used as a Bearer token when consuming the Management API.

Also, notice that access tokens have a fixed expiry. While you can keep issuing new tokens for the Client Credentials, please reuse tokens within their lifespan. This will be more performant and avoid flooding the Umbraco database with tokens.

The following code sample demonstrates how to consume the Management API by

1. Obtaining an access token from the token endpoint, and

2. Fetching data from the "current user" endpoint.

using System.Net.Http.Json;
using IdentityModel.Client;

// the base URL of the Umbraco site - change this to fit your setup
const string host = "https://localhost:44391";

var client = new HttpClient();

// request a client credentials token from the Management API token endpoint
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;
}

// use the access token as Bearer token
client.SetBearerToken(tokenResponse.AccessToken);

// fetch user data from the "current user" Management API endpoint
var apiResponse = await client.GetAsync($"{host}/umbraco/management/api/v1/user/current");
var apiUserResponse = await apiResponse
    .EnsureSuccessStatusCode()
    .Content
    .ReadFromJsonAsync<ApiUserResponse>();

if (apiUserResponse is null)
{
    Console.WriteLine("Could not parse a user from the API response.");
    return;
}

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

public class ApiUserResponse
{
    public required Guid Id { get; set; }

    public required string Name { get; set; }

    public required string Email { get; set; }
}

Management API

The Management API delivers headless management capabilities built directly into Umbraco. The Management API is used by the backoffice to communicate with the backend.

The Management API can also be used for Custom apps or Workflows with OpenID Connect.

Swagger Documentation

Umbraco ships with Swagger to document the Management API. Swagger and the Swagger UI are based on and is available at {yourdomain}/umbraco/swagger. For security reasons, both are disabled in production environments.

The Swagger documentation allows you to select a definition and go to either Umbraco Management API or Content Delivery API. If you are extending the Management API with your own controllers, you can also create custom documentation for these in Swagger. See and articles for details.

In the Swagger Umbraco Management API, you can find a collection of available endpoints in this version of Umbraco.

Authorization

The Management API endpoints are protected by the backoffice authorization policies and need an authentication token to interact with them.

To set the authorization, click on the Authorize button:

Then a popup will appear with some setup information and a login form for authorization:

The available integration for the authorization is done via a backoffice user with the integration of OAuth2, authorizationCode with PKCE. Swagger is only enabled in non-production environments, so if you need to access the Management API in production, you need a different client.

Test an Endpoint

To test a Management API endpoint, follow these steps:

1. Authenticate via the Authorize button. Make sure you use umbraco-swagger as the client_id:

1. Expand the first endpoint of Audit Log and click Try it out

1. You now have the option to change the values of the parameters. In this case, let´s leave the default values as they are.

2. Click on Execute so that we can get some data for our Audit Log endpoint.

In the Response Body we get the details of the Audit Log that we have requested.

1. You can continue changing the default parameters, clear the query, or cancel the trial of the endpoint.

Overview

This guide covers how to set up OAuth authorization for the Management API using Postman.

Before proceeding, make sure to read the article. It provides information about Authorization and why it is needed in this article.

This guide covers the following:

Importing the collection

1. Open the swagger UI at {yourdomain}/umbraco/swagger.

2. Choose Umbraco Management API from Select a definition.

3. Open the JSON file, which you can find right underneath the Title:

1. Save the JSON file to disk. The name of the file will be saved by default with the name of swagger.json.

3. Import the swagger.json file.

4. Choose Postman Collection when prompted.

Once imported, you will see a new collection called Umbraco Management API.

Setup Authorization

Setup Variables Values

1. Click on Variables tab in the Umbraco Management API collection.

2. Add a new variable called baseUrl and in the Initial and Current values add your URL, which in this example we use the localhost URL (without trailing slashes):

1. Save the changes.

Setup Authorization Values

To set up authorization values, follow these steps:

1. Click on Authorization tab in the Umbraco Management API collection.

2. Choose OAuth 2.0 from Type

3. Check if these attributes are set:

• Add auth data is set to Request Headers

• Auto-refresh token is Disabled

Configure Token

Now let's setup a new token:

1. Add a Token name called BackofficeSwagger under Configure New Token. The token name can be anything.

2. Choose Authorization Code (With PKCE) from Grant Type.

3. Click to enable Authorize using browser on Callback URL.

4. Add the following on Auth URL:

1. Add the following on Access Token URL:

1. Add umbraco-postman on Client ID.

2. Choose SHA-256 from Code Challenge Method .

3. Choose Send Client credentials in body from Client Authentication.

4. Any other field should either be empty or auto-filled by default.

5. Click Save.

6. Click on Get New Access Token. A window appears to authenticate into the Backoffice. Follow the given instruction to Open in Postman.

• You will see a new Manage access tokens window in Postman.

1. Click Use Token.

Get a token for a new user

1. Click on Authorization tab in the Umbraco Management API collection .

2. Click on Clear Cookies at the bottom of the page above the Get New Access Token.

3. Open your localhost instance of Umbraco in the browser. Example: https://localhost:44331.

4. Inspect the page, go to Application tab and clear the UmbracoBackOffice cookie.

5. Click on Get New Access Token in Postman and

6. Click on Use Token after authentication.

Common pitfalls and errors

Missing agent

SSL Certificate verification

When requesting a token, you might get an error that reads Error: unable to verify the first certificate in the console. To resolve this:

1. Click on the Settings cog wheel in the top right corner next to the Invite button.

1. Click on Settings and disable SSL certificate verification.

Making a request

When making a request for the first time, follow these steps:

1. Click on the Authorization tab in the Umbraco Management API collection.

2. Choose Inherit auth from parent from Type.

3. Disable any parameters you are not using as Postman sets their value to default sometimes.

4. Click Save