> ## 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 keys

> List, create, and revoke the API keys that connect endpoints to your workspace.

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](/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

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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

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

Use your MDM to update API keys on MDM-managed endpoints. See [deploy overview](/deploy/overview).