# Setup OAuth using Postman

## Overview

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

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

Before proceeding, make sure to read the [Management API](https://docs.umbraco.com/umbraco-cms/reference/management-api) article. It provides information about Authorization and why it is needed in this article.

This guide covers the following:

1. [Importing the collection](#importing-the-collection)
2. [Setup authorization](#setup-authorization)
3. [Get a token for a new user](#get-a-token-for-a-new-user)
4. [Common pitfalls and errors](#common-pitfalls-and-errors)

## 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**:

![JSON file location](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-463023ea8fe9b2c85195ced201a5c72d651b8c15%2Fpostman-setup-swagger-json-file.png?alt=media)

4. Save the JSON file to disk. The name of the file will be saved by default with the name of `swagger.json`.
5. Click to [create a new collection](https://learning.postman.com/docs/collections/using-collections/#creating-collections) in Postman.
6. Import the `swagger.json` file.
7. Choose **Postman Collection** when prompted.

![Postman import JSON file as collection](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-376d417974bcc9c8775ded1ec85d501cac52f019%2Fpostman-setup-swagger-import.png?alt=media)

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):

```http
https://localhost:44331
```

{% hint style="info" %}
The localhost URL might vary from this example. Make sure to change the URL to the current localhost URL your project is running on.
{% endhint %}

3. 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**:

```http
{{baseUrl}}/umbraco/management/api/v1/security/back-office/authorize
```

5. Add the following on **Access Token URL**:

```http
{{baseUrl}}/umbraco/management/api/v1/security/back-office/token
```

6. Add `umbraco-postman` on **Client ID**.
7. Choose `SHA-256` from **Code Challenge Method** .
8. Choose `Send Client credentials in body` from **Client Authentication**.
9. Any other field should either be empty or auto-filled by default.
10. Click **Save**.
11. 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.

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

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 [Postman website](https://www.postman.com/downloads/postman-agent/) and try again.

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

![Postman Cog Wheel Location](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-e15b2156bf8e53e5a2568e470520ae29022e3695%2Fpostman-setup-swagger-cog-wheel.png?alt=media)

2. 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**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/umbraco-cms/reference/management-api/postman-setup-swagger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.