# REST API

{% hint style="warning" %}

#### Availability

This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details.
{% endhint %}

{% hint style="warning" %}
API functionality:

1. requires Defguard version 1.2.4+
2. is also **available without enterprise license**, if your instance does not exceed the limits [described here](https://docs.defguard.net/enterprise/license#enterprise-is-free-up-to-certain-limits).
   {% endhint %}

## REST API documentation

You can explore the Defguard REST API using [Swagger UI](https://swagger.io/tools/swagger-ui/) by going to `<YOUR_DEFGUARD_URL>/api-docs`.

API specification JSON in OpenAPI format can also be fetched from `<YOUR_DEFGUARD_URL>/api/v1/api-docs`.

Admin users can generate API tokens to enable request authentication for custom external tools which use Defguard REST API.

Tokens retain the same access permissions as their owner, so be careful when sharing them with others.

## Generating API token

## Setup

To generate a new API token, go to your profile page and click the `Add new API Token`button:

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-58825bc8941a753e11a16718cc7b67744ce76210%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Fill in your chosen token name and submit form:

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-b8cc431414f11d8dfce83dfa8c7dc96e006663ab%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Copy generated token. This is the only time the token will be available in plain text form. If you lose it you will have to generate a new one.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-14c78bd775e20d711016ba3e1e78b2bab6d6df78%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

In the API token list you can later rename or delete a token:

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-ca7e7c256aa0941e75813955641604e00763f956%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Usage

Defguard API uses a standard **Bearer token authentication** scheme.

This means that an API token can be passed in the `Authorization` header to authenticate a given request instead of a session cookie used by the web UI:

```bash
Authorization: Bearer <token>
```

Example GET request:

```bash
curl -H "Authorization: Bearer <token>" <YOUR_DEFGUARD_URL>/api/v1/me
```

## Swagger UI

### Using API token in Swagger

After opening Swagger UI you can add your `API token` and try out available endpoints.

1. Open Swagger UI and click **Authorize** button.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-a90384462252049a534d715feb5d54e6bd688ccc%2F1.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Paste your `API token.`

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-938e5e62f8ff4cdce871cf01a7bc80633694204b%2F2.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Click on endpoint and select **Try it out** option.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-5f4b8f7b58ea177f1a1f9ef10fe09bfbaf038d58%2F3.png?alt=media" alt=""><figcaption></figcaption></figure>

4. If endpoint requires a path or request body, enter it.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-14c3558c64ab35c88bd2f6f75dbe1372b2ad32f9%2F4.png?alt=media" alt=""><figcaption></figcaption></figure>

5. Click **Execute** and scroll down, you will see response body.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-0e6519c1065ee655983f959f0dae61e497cfb2c6%2F5.png?alt=media" alt=""><figcaption></figcaption></figure>

### Schemas

If you are looking for definitions of types, you can scroll down to **Schemas** section.

<figure><img src="https://3466771104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe86iamwJVSYnIRsyVEAV%2Fuploads%2Fgit-blob-b307bd695da497ca3b97f4e500bcf5857408f000%2F6.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# 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.defguard.net/features/integrations/api-tokens.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.