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.
Swagger Documentation
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.
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-20310b094213bd79a5c5600f1bf2e4c618a86e4e%252Fmanagement-api-swagger.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=1900752&sv=1)
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:
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-a4486a55b2dbda61a667bdfb0d48fc68167beee7%252Fmanagement-api-swagger-authorize-button.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=81e2166&sv=1)
Then a popup will appear with some setup information and a login form for authorization:
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-2912c91fc61801abb080b3389b2a65538e4a9044%252Fmanagement-api-swagger-authorize-instructions.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5d349a99&sv=1)
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.
Test an Endpoint
To test a Management API endpoint, follow these steps:
Authenticate via the Authorize button. Make sure you use
umbraco-swagger
as theclient_id
:
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-63ce196e45057ec80807d2c5e9c397fe25320def%252Fmanagement-api-swagger-authenticated.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=1a636372&sv=1)
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
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-8a0ab27c21919fb191bcec0d8f025219275fb92c%252Fmanagement-api-try-it-out.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=1069b795&sv=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.
Click on Execute so that we can get some data for our Audit Log endpoint.
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F3701346516-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FG1Byxw7XfiZAj8zDMCTD%252Fuploads%252Fgit-blob-fa8ae962a61836c6a236577996354efa1c84efc6%252Fmanagement-api-execute-response.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5b88e68c&sv=1)
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.
Last updated