API keys - Kontext

Pass an API key to kontext setup --token to connect an endpoint to your workspace. The endpoint uses it to report activity. Kontext manages API keys as install tokens under /install-tokens.

Personal and workspace API keys

Kind	Where to create it	What it does
Personal API key	Get started	Connects one endpoint and links it to the person who created the key. It cannot connect a second endpoint. An unused key expires after 24 hours. After it expires, get a new command from Get started.
Workspace API key	Settings → API Keys	Connects endpoints without an associated person. `kontext whoami` shows `none (workspace key)`.

Settings → API Keys is only available to owners and admins in self-serve workspaces. The dashboard shows each key once, at creation.

Routes

Use a service account or connected agent with Deployments scopes. The caller must act as an owner or admin. See API overview for authentication.

Method	Path	Scope
GET	`/organizations/current/install-tokens`	`management:deployments:read`
POST	`/organizations/current/install-tokens`	`management:deployments:write`
POST	`/organizations/current/install-tokens/{tokenSha256}/revoke`	`management:deployments:write`

Kontext resolves current to the caller’s workspace.

List keys

curl --fail-with-body \
  'https://api.kontext.security/api/v1/organizations/current/install-tokens' \
  --header "Authorization: Bearer $KONTEXT_ACCESS_TOKEN"

The response contains metadata without API key values:

Field	Meaning
`tokenSha256`	SHA-256 digest of the key. Use it to revoke the key.
`label`	Your label from creation or `null`.
`ownerEmail`	The personal key’s owner or `null` for workspace keys.
`createdAt`	The key’s creation time.
`lastUsedAt`	When an endpoint last used the key or `null`.
`revokedAt`	The key’s revocation time or `null`.

Create a key

curl --fail-with-body \
  'https://api.kontext.security/api/v1/organizations/current/install-tokens' \
  --header "Authorization: Bearer $KONTEXT_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "label": "Build agents" }'

You can omit the body. The label limit is 100 characters. Set personal to true for a personal key owned by the person the caller acts as. Service accounts have no associated person and can create only workspace keys. The response contains token and tokenSha256. This is the only response that includes token. Kontext stores only its digest. Pass token to kontext setup --token or kontext setup --token-stdin on the endpoint.

Revoke a key

curl --fail-with-body --request POST \
  "https://api.kontext.security/api/v1/organizations/current/install-tokens/$TOKEN_SHA256/revoke" \
  --header "Authorization: Bearer $KONTEXT_ACCESS_TOKEN"

Use the 64-character tokenSha256 from the list. A successful response contains { "ok": true }. Endpoints using the API key stop reporting to your workspace. You cannot undo revocation. Kontext remains installed on those endpoints. Your workspace keeps their past activity.

Rotate a key

Create a new key.
Run kontext setup --token <new-key> on each endpoint using the old key. Kontext replaces the stored key and restarts the daemon.
Run kontext whoami to confirm the endpoint reports to the right workspace.
Revoke the old key once no endpoint depends on it.

Use your MDM to update API keys on MDM-managed endpoints. See deploy overview.

​Personal and workspace API keys

​Routes

​List keys

​Create a key

​Revoke a key

​Rotate a key