# 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.

{% hint style="info" %}
The Management API is a replacement for the backoffice controllers that lacked RESTful capabilities.
{% endhint %}

### Swagger Documentation

Umbraco ships with Swagger to document the Management API. Swagger and the Swagger UI are based on [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/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](https://docs.umbraco.com/umbraco-cms/reference/custom-swagger-api) and [Creating a backoffice API](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-backoffice-api) articles for details.

![Umbraco Management API documentation in Swagger](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-20310b094213bd79a5c5600f1bf2e4c618a86e4e%2Fmanagement-api-swagger.png?alt=media)

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:

![Umbraco Management API Authorize Button](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-a4486a55b2dbda61a667bdfb0d48fc68167beee7%2Fmanagement-api-swagger-authorize-button.png?alt=media)

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

![Umbraco Management API Authorize Login](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-2912c91fc61801abb080b3389b2a65538e4a9044%2Fmanagement-api-swagger-authorize-instructions.png?alt=media)

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.

{% hint style="info" %}
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](https://docs.umbraco.com/umbraco-cms/reference/management-api/postman-setup-swagger) article.
{% endhint %}

## 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](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-63ce196e45057ec80807d2c5e9c397fe25320def%2Fmanagement-api-swagger-authenticated.png?alt=media)

{% hint style="info" %}
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.
{% endhint %}

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

![Umbraco Management API Endpoint - Try it Out Button](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-8a0ab27c21919fb191bcec0d8f025219275fb92c%2Fmanagement-api-try-it-out.png?alt=media)

3. You now have the option to change the values of the **parameters**. In this case, let´s leave the default values as they are.
4. Click on **Execute** so that we can get some data for our **Audit Log** endpoint.

![Umbraco Management API Endpoint - Execute - Response](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-fa8ae962a61836c6a236577996354efa1c84efc6%2Fmanagement-api-execute-response.png?alt=media)

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

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