Get started with the 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.
Umbraco ships with Swagger to document the Management API. Swagger and the Swagger UI are based on Swashbuckle.AspNetCore 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 Custom Swagger API and Creating a backoffice API articles for details.
In the Swagger Umbraco Management API, you can find a collection of available endpoints in this version of Umbraco.
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.
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.
To test a Management API endpoint, follow these steps:
Authenticate via the Authorize button. Make sure you use umbraco-swagger as the client_id and leave the client_secret blank in non-production environments:
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.
Expand the first endpoint of Audit Log and click Try it out
You now have the option to change the values of the parameters. In this case, let´s leave the default values as they are.
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.
You can continue changing the default parameters, clear the query, or cancel the trial of the endpoint.
Setup OAuth authorization for swagger via Postman
This guide is created by a community member and is not managed by Umbraco HQ. Some attributes may change in the future because of the integration with Postman (third-party tool).
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:
Open the swagger UI at {yourdomain}/umbraco/swagger.
Choose Umbraco Management API from Select a definition.
Open the JSON file, which you can find right underneath the Title:
Save the JSON file to disk. The name of the file will be saved by default with the name of swagger.json.
Import the swagger.json file.
Choose Postman Collection when prompted.
Once imported, you will see a new collection called Umbraco Management API.
Click on Variables tab in the Umbraco Management API collection.
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):
The localhost URL might vary from this example. Make sure to change the URL to the current localhost URL your project is running on.
Save the changes.
To set up authorization values, follow these steps:
Click on Authorization tab in the Umbraco Management API collection.
Choose OAuth 2.0 from Type
Check if these attributes are set:
Add auth data is set to Request Headers
Auto-refresh token is Disabled
Now let's setup a new token:
Add a Token name called BackofficeSwagger under Configure New Token. The token name can be anything.
Choose Authorization Code (With PKCE) from Grant Type.
Click to enable Authorize using browser on Callback URL.
Add the following on Auth URL:
Add the following on Access Token URL:
Add umbraco-postman on Client ID.
Choose SHA-256 from Code Challenge Method .
Choose Send Client credentials in body from Client Authentication.
Any other field should either be empty or auto-filled by default.
Click Save.
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.
Click Use Token.
Click on Authorization tab in the Umbraco Management API collection .
Click on Clear Cookies at the bottom of the page above the Get New Access Token.
Open your localhost instance of Umbraco in the browser. Example: https://localhost:44331.
Inspect the page, go to Application tab and clear the UmbracoBackOffice cookie.
Click on Get New Access Token in Postman and
Click on Use Token after authentication.
When requesting a token, you might get an error that reads Error: unable to verify the first certificate in the console. To resolve this:
Click on the Settings cog wheel in the top right corner next to the Invite button.
Click on Settings and disable SSL certificate verification.
When making a request for the first time, follow these steps:
Click on the Authorization tab in the Umbraco Management API collection.
Choose Inherit auth from parent from Type.
Disable any parameters you are not using as Postman sets their value to default sometimes.
Click Save
Click to in Postman.
When trying to obtain a token you might run into an error. If you see the message Error: localhost request not supported in the Postman console, it means the Postman agent is missing. To resolve this issue, you can download the Postman agent from the Postman website and try again.
