# API keys

## What this covers

Project-scoped machine keys. The plaintext is returned once, at creation, and never again; a key carries an explicit scope set and cannot be widened after the fact.

Every example below runs as written once these are exported:

```bash
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export KEY_ID="<uuid>"
```

A `<value>` inside a JSON body is a value you supply. Responses are JSON; every error body is `{ "detail": … }`. Each schema is expanded once per page, where it first appears.

### Account door errors

| Status | Cause |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate. |
| `403` | The account is suspended or its email is not verified. |

## Operations — account session

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

### GET `/v2/api-keys`

List the project's keys: prefix, scopes and usage timestamps, never the plaintext.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `list_v2_keys_v2_api_keys_get` |
| Success | `200` `ApiKeyInfo[]` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | query | uuid or null | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `include_revoked` | query | boolean | no |  |

#### `ApiKeyInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `created_at` | date-time | yes |  |
| `id` | uuid | yes |  |
| `key_prefix` | string | yes |  |
| `last_used_at` | date-time or null | yes |  |
| `name` | string | yes |  |
| `project_id` | uuid or null | yes |  |
| `revoked_at` | date-time or null | yes |  |
| `scopes` | string[] | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/api-keys?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/v2/api-keys`

Mint a project key with an explicit scope set. This is the only response that ever carries the plaintext.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `create_v2_key_v2_api_keys_post` |
| Success | `201` `CreatedKeyResponse` |

Request body: `CreateV2KeyRequest`.

#### `CreateV2KeyRequest`

Canonical v2 create with a required, explicit permission set.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `project_id` | uuid | yes |  |
| `scopes` | string[] | yes | min 1 item(s); max 32 item(s) |

#### `CreatedKeyResponse`

The ONLY response that ever carries the plaintext.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `key` | ApiKeyInfo | yes |  |
| `plaintext` | string | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/api-keys" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-server",
    "project_id": "<project uuid>",
    "scopes": [
      "voice:read",
      "voice:write"
    ]
  }'
```

### DELETE `/v2/api-keys/{key_id}`

Revoke a key immediately. Revocation cannot be undone; mint a replacement first if the key is live.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `revoke_v2_key_v2_api_keys__key_id__delete` |
| Success | `200` `ApiKeyInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

---

Source: https://developers.dvaarik.com/docs/api/api-keys · every page as one file: https://developers.dvaarik.com/docs.md