Management API

Get started with the Management API.

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.

The Management API is a replacement for the backoffice controllers that lacked RESTful capabilities.

OpenAPI Documentation

Umbraco uses Microsoft.AspNetCore.OpenApi to document the Management API. The OpenAPI document and Swagger UI are both available at {yourdomain}/umbraco/openapi, and both are disabled in production environments for security reasons.

The OpenAPI 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. See Custom Backoffice API and Creating a backoffice API articles for details.

Umbraco Management API documentation in Swagger UI

In the Umbraco Management API OpenAPI document, 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:

Umbraco Management API Authorize Button

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

Umbraco Management API Authorize Login

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

In production environment, only 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.

You can see an example of how to connect a backoffice user via OAuth2 in Postman in the Swagger Setup in Postman article.

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:

Umbraco Management API when Authenticated

In non-production environments, you will always need only the client_id to authenticate. The client_secret should always be left blank, as the authentication flow does not use a client secret.

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

Umbraco Management API Endpoint - Try it Out Button

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.

Umbraco Management API Endpoint - Execute - Response

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.