# API keys

> Tenant API keys. The full key is shown once.

Canonical: https://docs.whabuzz.com/api/api-keys/

Tenant API keys. The full key is shown once.

Base URL `https://api.whabuzz.com`. Every request needs `Authorization: Bearer <key>` unless the operation says otherwise; see [Authentication](https://docs.whabuzz.com/authentication.md). Errors follow the [two-source contract](https://docs.whabuzz.com/errors.md).

Operations on this page:

- [`GET /v1/api-keys`](#listApiKeys): List API keys (prefix only)
- [`POST /v1/api-keys`](#createApiKey): Create an API key
- [`DELETE /v1/api-keys/{key_id}`](#revokeApiKey): Revoke a key now
- [`POST /v1/api-keys/{key_id}/rotate`](#rotateApiKey): Rotate a key

## List API keys (prefix only) {#listApiKeys}

`GET /v1/api-keys`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `listApiKeys`.

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/api-keys" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Keys

```json
{
  "data": [
    {
      "id": "0b9f8e7d-6c5b-4a39-8271-605f4e3d2c1b",
      "name": "Production",
      "environment": "live",
      "prefix": "wb_live_EXAMPLEKEY0000",
      "created_at": "2026-10-16T09:10:00Z",
      "last_used_at": "2026-10-16T09:40:00Z",
      "expires_at": null,
      "revoked_at": null
    }
  ]
}
```

## Create an API key {#createApiKey}

`POST /v1/api-keys`

The full key is in this response only. Store it now.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `createApiKey`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `environment` | `live` or `test` | no | Default `"live"`. |

Request example:

```json
{
  "name": "Production",
  "environment": "live"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/api-keys" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production",
  "environment": "live"
}'
```

**Responses**

**201** Created

```json
{
  "id": "0b9f8e7d-6c5b-4a39-8271-605f4e3d2c1b",
  "name": "Production",
  "environment": "live",
  "prefix": "wb_live_EXAMPLEKEY0000",
  "key": "wb_live_EXAMPLEKEY000000000000000000000000",
  "created_at": "2026-10-16T09:10:00Z"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 403 | `forbidden` | Not allowed for this caller |

## Revoke a key now {#revokeApiKey}

`DELETE /v1/api-keys/{key_id}`

Takes effect within 30 seconds everywhere.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `revokeApiKey`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | string (uuid) | yes |  |

cURL:

```bash
curl -X DELETE "https://api.whabuzz.com/v1/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Revoked

```json
{
  "id": "0b9f8e7d-6c5b-4a39-8271-605f4e3d2c1b",
  "revoked_at": "2026-10-16T11:00:00Z"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 404 | `not_found` | Not found |

## Rotate a key {#rotateApiKey}

`POST /v1/api-keys/{key_id}/rotate`

Returns a new key. The old key keeps working for 24 hours, then expires.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `rotateApiKey`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | string (uuid) | yes |  |

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**201** New key

```json
{
  "id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a49382716",
  "name": "Production",
  "environment": "live",
  "prefix": "wb_live_EXAMPLEKEY0000",
  "key": "wb_live_EXAMPLEKEY000000000000000000000000",
  "replaces": "0b9f8e7d-6c5b-4a39-8271-605f4e3d2c1b",
  "old_key_expires_at": "2026-10-17T11:00:00Z"
}
```