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

# API keys

> Issue and revoke personal API keys

A **personal API key** (`byk_`-prefixed) is the user-principal credential most CLI, SDK, and direct API calls authenticate with — see [Authentication](https://docs.bonya.ai/authentication.md) for how it's used on requests. This page covers managing the keys themselves.

> [!NOTE]
>
> Key management is **JWT-only** — keys can never manage keys. Every operation below requires a `supabaseJwt` and rejects a `byk_` key, even one belonging to the same user.

## Listing keys

```
GET /v1/api-keys
```

Returns `APIKeyListResponse`: `{ "api_keys": [ ...APIKey ] }`. Each entry exposes only a masked view of the key:

**key\_id** `string` *required*

Identifier for the key, used to revoke it.

**name** `string`

Optional display label, up to 128 characters.

**display\_prefix** `string` *required*

The key's prefix, for identifying it without exposing the secret.

**display\_last4** `string` *required*

The last 4 characters of the secret.

**created\_at** `string` *required*

Creation timestamp.

**revoked\_at** `string`

Revocation timestamp, if revoked.

## Creating a key

```
POST /v1/api-keys
```

Request body (`APIKeyCreateRequest`, optional):

**name** `string`

Display label, up to 128 characters.

Returns `201` with `APIKeyCreateResponse`:

**api\_key** `object` *required*

The new key's `APIKey` metadata (masked, as in list).

**secret** `string` *required*

The full secret value. Store it as a user-principal API key.

> [!WARNING]
>
> `secret` is shown **exactly once**, in the create response. There is no way to retrieve it again afterward — list only ever returns `display_prefix`/`display_last4`. If it's lost, revoke the key and create a new one.

## Revoking a key

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

Returns `204` on success.

## Related

> [card] [Authentication](https://docs.bonya.ai/authentication.md)

> [card] [Organizations](https://docs.bonya.ai/concepts/organizations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.