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

# API Keys (V3): Programmatic Key Management

> Manage Snappy API keys programmatically in V3 - list, create, and revoke keys by authenticating with an existing API key.

The V3 API Keys endpoints let you manage keys programmatically - listing, creating, and revoking keys - by authenticating with an existing API key (`X-Api-Key`). You can also create and manage keys in the Snappy dashboard on the **Sharing & Access** page.

<Tip>
  For the full authentication concept guide - including how scopes work, how to use mTLS, and best practices for key rotation - see [Snappy API Authentication: API Keys, Scopes & mTLS](/pages/authentication-and-security).
</Tip>

<Note>
  The [V2 API Keys](/modules/api/v2/api-keys/overview) endpoints offer the same list, create, and delete operations using V2 conventions.
</Note>

***

## The API Key Object

The V3 response shape **never includes the secret value**, even on creation responses. Treat the secret as opaque once issued.

| Field            | Type              | Description                                                                       |
| :--------------- | :---------------- | :-------------------------------------------------------------------------------- |
| `id`             | string            | Unique identifier of the API key                                                  |
| `name`           | string            | Display name (unique within the Company)                                          |
| `companyId`      | string            | The ID of the Company the key belongs to                                          |
| `createdAt`      | string (ISO 8601) | When the key was created                                                          |
| `expirationDate` | string (ISO 8601) | When the key expires. `null` if the key has no expiration.                        |
| `enforceMtls`    | boolean           | When `true`, requests with this key must use mTLS                                 |
| `permissions`    | array             | Permission scopes granted to this key (e.g. `gifts:create`, `orders:read:masked`) |
| `accountsAccess` | object            | Account scope: `{ scope: "all-accounts" \| "specific-accounts", ids: [] }`        |

***

## Key Concepts

#### Maximum 100 active keys per Company

Companies can have up to 100 active API keys at any time.

#### Page-number pagination

The List endpoint uses **page-number pagination** (`page[number]`, `page[size]`), with the standard V3 `links` envelope (`first`, `next`, `prev`).

#### Standard V3 error envelope

Errors follow the standard V3 shape: `{ message, errorCode, errors[] }` with structured error codes (e.g. `403_PBLC_001`) and dot-separated paths to field-level errors.

***

## How to Work with API Keys (V3)

**List API keys**

```text theme={null} theme={null}
GET /v3/authentication/api-keys
```

Returns a paginated list of the active API keys for your Company. Filter by Account access scope, paginate with `page[number]` / `page[size]`.

**Create an API key**

```text theme={null} theme={null}
POST /v3/authentication/api-keys
```

Creates a new API key. The secret value is returned in this response only.

**Delete an API key**

```text theme={null} theme={null}
DELETE /v3/authentication/api-keys/{apiKeyId}
```

Permanently deletes the specified key. Returns `204 No Content` on success.