> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Overview

> Create and manage API keys programmatically. Supports personal keys (user-scoped) and service keys (project-scoped, for automation).

## Intro

The API Keys API lets you create, list, and revoke API keys for your organization. Two key types are supported:

* **Personal keys** — tied to a user, inherit the user's RBAC permissions
* **Service keys** — no user association, scoped to specific projects with ADMIN access. Ideal for CI/CD, scaffolding tools, and service-to-service integrations

## Authentication

Requires an **organization-level API key**. Pass it as a Bearer token:

```
Authorization: Bearer sk-lw-<id>_<secret>
```

Reading your own keys needs `organization:view`. Creating, updating and revoking need `organization:manage`. Reading or listing keys that belong to somebody else needs `organization:manage` **and** organization administrator membership.

Service keys are the exception, because they belong to nobody. A member credential with `organization:view` sees the organization's service keys in its own listing and may read one by id: administrator membership is what minting a service key takes, not what reading one takes. A service credential acts as nobody and so owns no keys at all, which makes its only listing the organization-wide one, and that needs `organization:manage`.

## Endpoints

| Method   | Path                 | Description                                |
| -------- | -------------------- | ------------------------------------------ |
| `GET`    | `/api/api-keys`      | List API keys                              |
| `POST`   | `/api/api-keys`      | Create a new API key                       |
| `GET`    | `/api/api-keys/{id}` | Read one key and the access it carries     |
| `PATCH`  | `/api/api-keys/{id}` | Update a key's name, description or access |
| `DELETE` | `/api/api-keys/{id}` | Revoke an API key                          |

## Reading a key back

`GET /api/api-keys/{id}` and `PATCH /api/api-keys/{id}` return the same body, and it contains every field a write accepts. `bindings` comes back in exactly the shape `POST` and `PATCH` take, so comparing what you asked for against what the key has is a comparison rather than a translation. The secret itself is never returned: it exists only in the create response.

A personal key belonging to somebody else is readable only with organization administrator membership plus `organization:manage`. Without both, the id answers 404 rather than 403, because a 403 would confirm the key exists. Service keys are the exception described above: a member credential with `organization:view` reads one by id.

## Updating

`PATCH` is partial at the field level: send `name` alone and only the name changes. `bindings`, when you send them, replace the key's bindings outright, so what you send is what the key has afterward.

```bash theme={null}
curl -X PATCH https://app.langwatch.ai/api/api-keys/<api_key_id> \
  -H "Authorization: Bearer sk-lw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline (staging only)",
    "bindings": [
      { "role": "MEMBER", "scopeType": "PROJECT", "scopeId": "project_abc123" }
    ]
  }'
```

## Key Types

### Personal Keys

Created for a specific user. The key's effective permissions are the intersection of the key's bindings and the user's own role bindings (the "ceiling" model).

```json theme={null}
{
  "keyType": "personal",
  "name": "My dev key",
  "bindings": [
    { "role": "ADMIN", "scopeType": "ORGANIZATION", "scopeId": "<orgId>" }
  ]
}
```

A personal key is capped by the access of the person it belongs to. It defaults to the caller; `assignedToUserId` mints one for somebody else, and that key is then capped by their access rather than yours.

### Service Keys

Created without a user association (`userId: null`). Scoped to specific projects via `projectIds`. Each project gets an ADMIN binding automatically.

```json theme={null}
{
  "keyType": "service",
  "name": "CI pipeline key",
  "projectIds": ["project_abc123", "project_def456"]
}
```

<Info>
  Service keys without `projectIds` get org-wide ADMIN access. Always scope to specific projects when possible.
</Info>

Because a service key has no person capping it, and a key minted for somebody else is capped by their access rather than yours, both are reserved for organization administrators. A caller who holds `organization:manage` without being an administrator is refused with 403. Minting a personal key for yourself is always allowed: your own access caps it.

## Narrowing what a key may do

Three fields decide how far a key reaches:

* `bindings`, the roles the key holds and where, in the same `role` / `scopeType` / `scopeId` shape [role bindings](/docs/api-reference/role-bindings/overview) use.
* `permissionMode`, one of `all`, `readonly` or `restricted`. `all` and `readonly` take their meaning from the bindings alone.
* `permissions`, a list of `resource:action` keys. Only for `restricted` mode, where it is the exact set the key's `CUSTOM` bindings grant.

```json theme={null}
{
  "keyType": "service",
  "name": "Nightly evaluation runner",
  "permissionMode": "restricted",
  "permissions": ["project:view", "traces:view", "evaluations:create"],
  "bindings": [
    { "role": "CUSTOM", "scopeType": "PROJECT", "scopeId": "project_abc123" }
  ]
}
```

A key can never grant more than the person or organization behind it already has, whatever you put in these fields.