> ## 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 (V2): Programmatic Key Management

> Programmatically manage the API keys your Company uses to authenticate with the Snappy API - list, create, and revoke keys using an existing key for authentication.

The V2 API Keys endpoints let any service with a valid Snappy API key manage other keys programmatically - list active keys, create new ones, and revoke keys you no longer need. Use this when you need automated key rotation in a backend service or CI/CD pipeline.

<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 [V3 API Keys](/modules/api/v3/api-keys/overview) endpoints offer the same list, create, and delete operations using V3 JSON:API conventions. You can also create and manage keys in the Snappy dashboard on the **Sharing & Access** page.
</Note>

***

## The API Key Object

| Field            | Type              | Description                                                                       |
| :--------------- | :---------------- | :-------------------------------------------------------------------------------- |
| `id`             | string            | Unique identifier of the API key                                                  |
| `name`           | string            | Display name (unique within the Company)                                          |
| `apiKey`         | string            | The secret key value (24 hex characters). **Returned only on creation.**          |
| `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

#### The secret value is shown only once

When you create an API key, the secret `apiKey` value is returned in the response body. **This is the only time the value is visible** - it's hashed and stored, and cannot be retrieved later. If you lose it, delete the key and create a new one.

#### Maximum 100 active keys per Company

Companies can have up to 100 active API keys at any time. Plan rotations accordingly - typically you'd create the new key first, update your integrations to use it, then delete the old key.

#### Permission inheritance on creation

Keys created via this endpoint can only have permissions equal to or more restrictive than the calling key. This prevents privilege escalation: a key with read-only access cannot mint a key with write access.

#### mTLS for enhanced security

For production environments, set `enforceMtls: true` when creating a key. mTLS-enforced keys must connect through the dedicated mTLS endpoint (`https://mtls-api.snappy.com/public-api`) and present a valid client certificate. See the [Authentication & Security guide](/pages/authentication-and-security) for setup details.

***

## How to Work with API Keys (V2)

**List API keys**

```text theme={null} theme={null}
GET /v2/authentication/apiKeys
```

Returns the active API keys for your Company. Returns metadata only - the secret `apiKey` value is never included.

**Create an API key**

```text theme={null} theme={null}
POST /v2/authentication/apiKeys
```

Creates a new API key with the specified permissions, Account scope, expiration, and mTLS setting. The secret value is returned in this response only.

**Delete an API key**

```text theme={null} theme={null}
DELETE /v2/authentication/apiKeys/{apiKeyId}
```

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