knot knot

API Tokens

API tokens are automatically created when logging in with the Knot client. Additionally, tokens can be manually created and used to access the API from external applications.

Creating a Token

  1. From the menu, select API Tokens, then click New Token.

    Create API Token

  2. Complete the Name field to identify the token.

  3. Click Create Token to generate a new token.

  4. The list of available tokens will be displayed.

List of Available Tokens
  • Tip: Clicking on a token will copy it to the clipboard for easy use.

Tokens expire after two weeks of inactivity. Any API call made with the token will reset its lifespan.

Using a Token

Pass the token in the Authorization header of any API request:

curl -H "Authorization: Bearer <token>" https://knot.internal:3000/api/spaces

The token carries your permissions — it can do everything your account can do. See the API reference for every endpoint.

Scoping a Token

By default a token has Full Access — every endpoint your account can reach. Untick Full Access when creating (or editing) a token and it becomes scoped: only the ticked endpoint groups are reachable, everything else answers 403 token scopes do not permit this endpoint.

Scope Reach
Methods Discover and call space methods (/api/methods*).
MCP The MCP server endpoint (/mcp).
Tunnels Web and port tunnels only (/tunnel/*) plus the tunnel management API (/api/tunnels*) — list, create and delete tunnels and nothing else.

A Tunnels-only key is what a machine that should only ever expose a port wants:

knot tunnel http 8080 myapp --server https://knot.internal:3000 --token <tunnels-only-token>

Scopes narrow but never widen: a scoped token still passes through every permission check a full token does, and an unscoped token behaves exactly as before.

Deleting a Token

Deleting a token immediately prevents further API calls from being made using that token.

  1. From the API Tokens list, click Delete next to the token you want to remove.
  2. Confirm the operation when prompted.