> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent authorization

> Use the OAuth 2.0 device authorization flow to get a short-lived access token to manage webhook endpoints.

## Overview

Agent authorization allows your agent to manage settings that you would otherwise change in the [Knot Dashboard](https://dashboard.knotapi.com), such as [creating webhook endpoints](/api-reference/webhook-endpoints/create).

It does not use [Basic Authentication](/api-reference/authentication) with your `secret`. Instead, you approve each request for access in the [Knot Dashboard](https://dashboard.knotapi.com) and the agent receives a short-lived access token (expiring after 15 minutes) that acts on your behalf.

The authorization URL is `https://api.dashboard.knotapi.com` and it manages settings for both the Knot development and production environments. Each access token manages only the environment of the client ID it was issued for, so use your development client ID for development and your production client ID for production.

## Scopes

<table>
  <colgroup>
    <col width="144" />

    <col width="390" />
  </colgroup>

  <thead>
    <tr>
      <th>Scope</th>
      <th>Grants access to</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`webhooks:read`</td>
      <td>Get and list webhook endpoints.</td>
    </tr>

    <tr>
      <td>`webhooks:write`</td>
      <td>Create, update, and delete webhook endpoints.</td>
    </tr>
  </tbody>
</table>

## Permissions

The approving user's role determines what the access token can change:

| Role | Development webhook endpoints | Production webhook endpoints |
| - | - | - |
| **Owner** | Read and write | Read and write |
| **Admin** | Read and write | Read and write |
| **Member** | Read and write | Read only |

## Get an access token

<Steps>
  <Step title="Request a device code" titleSize="h3">
    Call [Request Device Code](/api-reference/agent-authorization/request-device-code) with your client ID for the environment you want to manage, found in the [Knot Dashboard](https://dashboard.knotapi.com), and the scopes you need. Never send your `secret`: requests that include it are rejected.

    ```bash Request theme={"system"}
    curl --request POST \
      --url https://api.dashboard.knotapi.com/oauth/device/code \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data client_id=9f3c2a1e-6b7d-4e8f-a2c4-5d6e7f8a9b0c \
      --data 'scope=webhooks:read webhooks:write'
    ```

    ```json Response theme={"system"}
    {
      "device_code": "def50200a1b2c3d4e5f6",
      "user_code": "WDJBMJHT",
      "verification_uri": "https://api.dashboard.knotapi.com/oauth/device",
      "verification_uri_complete": "https://api.dashboard.knotapi.com/oauth/device?user_code=WDJBMJHT",
      "expires_in": 600,
      "interval": 5
    }
    ```
  </Step>

  <Step title="Ask the user to approve the request" titleSize="h3">
    Show the user the `verification_uri` and the `user_code`. The user opens the link, logs in to the Knot Dashboard account that owns the client ID, enters the `user_code`, reviews the requested scopes, and approves. The codes expire after 10 minutes.

    <Warning>
      Only approve a request that you started yourself. Never approve a code someone else sent you, such as by email or chat. Approving it gives them access to your Knot Dashboard settings.
    </Warning>
  </Step>

  <Step title="Poll for the access token" titleSize="h3">
    Call [Request Access Token](/api-reference/agent-authorization/request-access-token) every `interval` seconds until it returns an access token. Stop on `access_denied`, `expired_token`, or `invalid_grant`.

    ```bash cURL theme={"system"}
    curl -X POST https://api.dashboard.knotapi.com/oauth/token \
      --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
      --data-urlencode "client_id=CLIENT_ID" \
      --data-urlencode "device_code=DEVICE_CODE"
    ```
  </Step>

  <Step title="Call the webhook endpoints" titleSize="h3">
    Send the access token in the `Authorization` header.

    ```bash cURL theme={"system"}
    curl -X POST https://api.dashboard.knotapi.com/webhook-endpoints/list \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"environment": "development"}'
    ```
  </Step>
</Steps>

## Handle access tokens safely

An access token grants access to your Knot Dashboard settings until it expires. If an AI agent makes these requests, the access token can appear in the agent's context and session transcript.

* Store the access token in a file readable only by your user (for example, mode `0600`) and reference it from there. Do not print it.
* Delete the file when you finish.
* Access tokens can't be revoked from the Knot Dashboard. They expire after 15 minutes, and removing the approving user or changing their role takes effect on the next request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.