API overview - Kontext

Your scripts, CI jobs and coding agents can read decisions through the Kontext management API. They can manage policies, API keys and directory sync. Use this base URL for the documented paths:

https://api.kontext.security/api/v1

Workspace owners and admins manage API access under Settings → Agent access.

Choose how to connect

Caller	How it authenticates	Access
Service account	You exchange a client ID and secret for an access token.	You choose scopes at creation.
Agent connected through the Kontext skill	You approve access in your browser. The agent’s token expires after an hour.	You set workspace-wide access under What a connected agent can do.

Use service accounts for CI and automation. Use the skill for Claude Code or Codex.

Service accounts

Open Settings → Agent access and click Create service account.
Give it a name, then pick an access preset or check individual scopes.
Copy the Client ID, Client secret, and Terminal environment block. The dashboard shows the secret once.

The Terminal environment block sets KONTEXT_CLIENT_ID, KONTEXT_CLIENT_SECRET, and KONTEXT_SCOPES. Request an access token with the OAuth client credentials grant:

curl --fail-with-body https://api.kontext.security/oauth2/token \
  --user "$KONTEXT_CLIENT_ID:$KONTEXT_CLIENT_SECRET" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode "scope=$KONTEXT_SCOPES" \
  --data-urlencode audience=https://api.kontext.security/api/v1

Send the returned access_token on every call:

Authorization: Bearer <access_token>

Open a service account to view its scopes, Rotate secret, or Revoke it. Kontext rejects the old secret immediately after rotation. Service accounts use their own scopes independently of connected agent settings. You can create, rotate or revoke service accounts only in the dashboard.

A service account acts as the admin who created it and inherits that person’s role. If that admin leaves the workspace, the service account stops authenticating. Create long-lived automation from an account you plan to keep.

Connected agents

Follow the two steps in Connect an agent. First, install the skill:

npx skills add kontext-security/agent-skills

Ask your agent to “Connect to Kontext and show me my policies.” Approve access once in your browser. The agent acts as you within What a connected agent can do. Set each area to Off, Read, or Read & write, or choose a preset. The dashboard saves each change on click. Kontext applies it to the agent’s next request.

Scopes and routes

Each area in Settings → Agent access maps to a read scope and a write scope. A write scope also grants read.

Area	Scopes	Routes
Policies	`management:policy:read`, `management:policy:write`	`/policy` and the routes under it, except `/policy/settings`. See Policies API.
Logs	`management:logs:read`	`GET /decisions`, `GET /decisions/{id}`
Directory	`management:directory:read`, `management:directory:write`	`GET /organizations/current/directory/status`, `/groups`, `/reconciliation`, and the SCIM token routes under `/organizations/current/directory/scim-tokens`. You need write access to create or revoke SCIM tokens.
Settings	`management:settings:read`, `management:settings:write`	`GET` and `PATCH /policy/settings` for the data collection mode, `GET /organizations/current/agent-access`
Deployments	`management:deployments:read`, `management:deployments:write`	`/organizations/current/install-tokens`, see API keys. For MDM-managed workspaces, `GET /deployments/releases`, `GET /deployments/releases/latest`, `POST /deployments/releases/{version}/artifacts/{kind}/download-url`

You can apply these presets:

Preset	Access
Read only	You can read every area.
Policy author	You can read and write Policies and read Logs.
Directory admin	You can read and write Directory and Settings and read Logs.
Deployment	You can read and write Deployments and read Logs.

Kontext checks the role of the person the caller acts as. Policy, directory, settings and API key routes require an owner or admin.

First request

Set KONTEXT_ACCESS_TOKEN to your token. With management:logs:read, you can list the five latest decisions through this read-only request.

curl --fail-with-body \
  'https://api.kontext.security/api/v1/decisions?limit=5' \
  --header "Authorization: Bearer $KONTEXT_ACCESS_TOKEN"

Kontext returns an items array and nextCursor. Pass nextCursor as cursor for the next page. Filter with sessionId, from, and to.

Errors

Status	Meaning
400	The request or a field in it is invalid.
401	The token is missing, expired, or invalid.
402	The workspace is over its plan’s included usage.
403	The caller lacks the role or scope the route needs.
404	The resource does not exist or the caller cannot see it.
409	The request conflicts with the resource’s current state.
412	You supplied an outdated version for a conditional write. Read the resource again and retry.
413	The request body is too large.
422	The policy failed validation.
428	A conditional write is missing its required header.
429	You sent too many requests. Slow down and retry.

If the caller lacks a required scope, Kontext names it in the response body and WWW-Authenticate header.

​Choose how to connect

​Service accounts

​Connected agents

​Scopes and routes

​First request

​Errors

Choose how to connect

Service accounts

Connected agents

Scopes and routes

First request

Errors