Agent authorization

Overview

Agent authorization allows your agent to manage settings that you would otherwise change in the Knot Dashboard, such as creating webhook endpoints. It does not use Basic Authentication with your secret. Instead, you approve each request for access in the Knot Dashboard 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

Scope	Grants access to
`webhooks:read`	Get and list webhook endpoints.
`webhooks:write`	Create, update, and delete webhook endpoints.

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

Request a device code

Call Request Device Code with your client ID for the environment you want to manage, found in the Knot Dashboard, and the scopes you need. Never send your secret: requests that include it are rejected.

Request

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'

Response

{
  "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
}

Ask the user to approve the request

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.

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.

Poll for the access token

Call Request Access Token every interval seconds until it returns an access token. Stop on access_denied, expired_token, or invalid_grant.

cURL

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"

Call the webhook endpoints

Send the access token in the Authorization header.

cURL

curl -X POST https://api.dashboard.knotapi.com/webhook-endpoints/list \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "development"}'

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.

Overview

Development

Sessions

CardSwitcher

TransactionLink

SubscriptionManager

Shopping

Merchants

Merchant Accounts

Detected Accounts

Users

Audit Logs