API tokens

A personal access token (PAT) is a bearer token for the API and the CLI. It belongs to you, and it can never do more than you can.

Creating one#

From your account's token page. You choose:

• a name, so you can tell them apart later;
• an expiry;
• one or more grants — a workspace and the scopes the token may use there.

Scopes use the same vocabulary as roles: Flow__Read, Execution__Write, and so on.

What a token may actually do#

The effective authority is the intersection:

granted scopes  ∩  your own permissions

Both halves are checked on every request, so a token narrows and never widens. Two consequences worth knowing:

• Being an owner does not carry over. An owner bypasses permission checks as a person; a token they create does not. Its grants always apply.
• Losing access revokes reach. If your role is narrowed, every token you hold narrows with it, immediately and without being reissued.

Grant the least a job needs. A token for a deploy pipeline needs Flow__Write and Deployment__Write; it almost certainly does not need Member__Write.

Using one#

curl -H "authorization: Bearer $KONNECTHUB_TOKEN" \
  https://your-konnecthub-host/api/v1/flows

The CLI reads KONNECTHUB_TOKEN from the environment, which is the first-class path for CI — konnecthub login opens a browser, and CI has none.

export KONNECTHUB_TOKEN=…
konnecthub deploy

Managing them#

Your token list shows each token's name, its grants, when it expires and when it was last used. "Last used" is the useful column: it is how you find a token nothing needs any more.

Revoking is immediate.

Tokens cannot mint tokens#

Only an interactive browser session can create a PAT. A request authenticated with a PAT is refused — otherwise a leaked narrow token could mint a broader one and escape its own cap.

Minting is also rate-limited per identity.

Sessions are not tokens#

Signing in creates a session, which is separate from your PATs: your account's sessions page lists where you are signed in and lets you end any of them. Revoking a token does not sign you out, and signing out does not revoke a token.

Next#

• Roles and permissions — the vocabulary a grant is written in.
• The CLI — where a token is normally used.