---
title: "API Keys"
description: "REST endpoints for api keys. Bearer-auth required."
section: "API"
group: "REST"
order: 14
---

## POST /api/api-keys

Create API key

Creates a new API key. The full key is returned only in this response — store it securely.

**Request body**

```json
{
  "workspaceId": "string",
  "name": "string",
  "type?": "private | public | session",
  "scopes?": {
    "operations?": ["<...>"],
    "entityIds?": ["<...>"]
  },
  "expiresIn?": "string",
  "ownerUserId?": "string"
}
```

**Response**

```json
{
  "id": "string",
  "name": "string",
  "key": "string",
  "keyHint": "string",
  "type": "private | public",
  "scopes?": {
    "operations?": ["<...>"],
    "entityIds?": ["<...>"]
  },
  "expiresAt": "string"
}
```

## PATCH /api/api-keys/{id}

Update API key

**Path parameters**

- `id` (required): The API key's prefixed ID.

**Request body**

```json
{
  "name?": "string"
}
```

**Response**

```json
{
  "id": "string",
  "workspaceId": "string",
  "type": "private | public | session",
  "name": "string",
  "keyHint": "string",
  "scopes?": {
    "operations?": ["<...>"],
    "entityIds?": ["<...>"]
  },
  "expiresAt": "string",
  "createdBy": "string",
  "ownerUserId": "string",
  "createdAt": "string",
  "lastUsedAt": "string"
}
```

## POST /api/api-keys/{id}/rotate

Rotate API key

Rotates the secret for an existing API key. The previous key is immediately invalidated. The new plaintext key is returned only in this response.

**Path parameters**

- `id` (required): The API key's prefixed ID.

**Response**

```json
{
  "id": "string",
  "name": "string",
  "key": "string",
  "keyHint": "string",
  "type": "private | public",
  "scopes?": {
    "operations?": ["<...>"],
    "entityIds?": ["<...>"]
  },
  "expiresAt": "string"
}
```