> ## Documentation Index > Fetch the complete documentation index at: https://docs.kontext.security/llms.txt > Use this file to discover all available pages before exploring further. # API overview > Authenticate to the Kontext management API and check the scopes each route requires. 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: ```text theme={"system"} 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 1. Open **Settings → Agent access** and click **Create service account**. 2. Give it a name, then pick an access preset or check individual scopes. 3. 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: ```bash theme={"system"} 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: ```http theme={"system"} Authorization: Bearer ``` 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: ```bash theme={"system"} 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](/api/policies). | | 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](/api/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. ```bash theme={"system"} 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.