> ## 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.

# Snappy API Authentication: API Keys, Scopes & mTLS

> Generate and rotate scoped API keys, manage granular permissions, scope requests by account or company, and configure Mutual TLS for enterprise integrations.

Snappy APIs are authenticated using scoped API keys passed in the `X-Api-Key` header. OAuth2 is not used. Enterprise customers may optionally enable Mutual TLS (mTLS) for additional network-level security.

<Tip>
  **The same API key works for both V2 and V3.** Pick the API version that matches the endpoint path (`/v2/...` vs `/v3/...`) - the authentication header is identical.
</Tip>

***

## Authentication at a glance

| Surface                                                                                          | Auth mode                    | Header                    | Notes                                                                                                |
| :----------------------------------------------------------------------------------------------- | :--------------------------- | :------------------------ | :--------------------------------------------------------------------------------------------------- |
| V3 APIs (Products, Variants, Collections, Orders, Accounts, Billing Methods, Swag, Export, etc.) | API key                      | `X-Api-Key: YOUR_API_KEY` | Same key as V2.                                                                                      |
| V2 APIs                                                                                          | API key                      | `X-Api-Key: YOUR_API_KEY` | Same key as V3.                                                                                      |
| API Keys Management (`/v2/authentication/apiKeys`, `/v3/authentication/api-keys`)                | API key                      | `X-Api-Key: YOUR_API_KEY` | Manage keys programmatically - see [Managing API Keys](#managing-api-keys).                          |
| Enterprise mTLS (optional)                                                                       | API key + client certificate | `X-Api-Key` + TLS cert    | Use the mTLS base URL - see [Enterprise Security: Mutual TLS](#enterprise-security-mutual-tls-mtls). |

***

## Authenticating Requests

To communicate with the Snappy API, you need an API key. You must include it in the header of **every** request using the `X-Api-Key` header:

```text theme={null}
X-Api-Key: YOUR_API_KEY
```

**Example request against a V3 endpoint:**

```bash theme={null}
curl --request GET \
  --url https://api.snappy.com/public-api/v3/accounts \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'accept: application/json'
```

**The same key against a V2 endpoint:**

```bash theme={null}
curl --request GET \
  --url https://api.snappy.com/public-api/v2/accounts \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'accept: application/json'
```

<Note>
  Create your first API key in the Snappy dashboard on the **Sharing & Access** page. After that you can manage keys in the dashboard or programmatically via the [**API Keys endpoints**](/modules/api/v3/api-keys/overview) - see [Managing API Keys](#managing-api-keys) below.
</Note>

### Base URLs

| Purpose                                                                                                      | Base URL                                 |
| :----------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
| Standard                                                                                                     | `https://api.snappy.com/public-api`      |
| mTLS (enterprise)                                                                                            | `https://mtls-api.snappy.com/public-api` |
| Append `/v2/...` or `/v3/...` to address the version you want. Both versions are served from both base URLs. |                                          |

***

## Optional Scoping Header (V3)

V3 endpoints accept an optional header that narrows a request to a specific sub-entity inside your organization. It is not required for getting started - omit it and the request runs against the full org reachable by the API key.

| Header                                                                                                                                                               | Description                                                  |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| `Snappy-Account-Id`                                                                                                                                                  | Scope the request to a specific Account within your Company. |
| Header names are RFC 6648 compliant - no `X-` prefix. Headers themselves are case-insensitive in transit; the casing shown here is the canonical documentation form. |                                                              |

<Note>
  A small number of V3 endpoints - currently the Collections list and by-ID endpoints - **require** `Snappy-Account-Id` because the response depends on account-level visibility. Each endpoint's reference page notes when this applies.
</Note>

***

## Managing API Keys

There are two ways to manage your Company's API keys:

* **Dashboard (UI)** - create and manage keys on the **Sharing & Access** page under Company Settings. This is where you create your first key.
* **API** - list, create, and delete keys programmatically by authenticating with an existing API key (`X-Api-Key`). A key can only create or revoke other keys with permissions equal to or more restrictive than its own, which prevents privilege escalation.

See [API Keys V3](/modules/api/v3/api-keys/overview) for the full management reference.

***

## API Permissions & Key Management

### Overview

To help you meet modern enterprise security standards and enforce the **Principle of Least Privilege**, Snappy uses scoped API keys. You can restrict exactly what each key is allowed to do, minimizing security risks.
When generating a key in the dashboard, you can assign specific permissions based on the integration's exact needs:

* **Read-only access:** Allow an integration to retrieve data (gift statuses, catalog items, order tracking) without the ability to spend budget or place orders.
* **Full access:** Allow an integration to create orders, manage recipients, and run campaigns.
* **Account-level scoping:** Restrict a key so it can only operate within a specific sub-account rather than your entire Company.

<Note>
  Each environment (Testing and Production) has its own set of API keys. Never use a Production key in your test environment or vice versa.
</Note>

<Tip>
  Always assign the minimum required permissions necessary for your integration to function.
</Tip>

### Available Scopes

Scopes are common across V2 and V3 - assigning `products:read` to a key, for example, grants access to both `/v2/products` and `/v3/products` endpoints. The table below lists every available scope and which endpoints it unlocks.

| Permission                     | Scope                                                | Description                                                             | Notes                                                                                                              |
| :----------------------------- | :--------------------------------------------------- | :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| **Create & Update Gifts**      | `gifts:create`, `gifts:update`                       | Create or update gifts for recipients and notify them.                  | V2 Gifts API. V3 uses Orders instead - see `orders:*`.                                                             |
| **Read Gifts**                 | `gifts:read:masked`, `gifts:read:unmasked`           | Retrieve gift information, including recipients.                        | Sensitive Information. V2 only.                                                                                    |
| **Create a Demo Gift**         | `gifts:create:demo`                                  | Create a demo gift that can be shared.                                  | `POST /v2/gifts/demo`. V2 only.                                                                                    |
| **Create an Order**            | `orders:create`                                      | Place an order.                                                         | Billable action. Covers V2 `POST /orders` and V3 `POST /v3/orders`.                                                |
| **Read Orders**                | `orders:read:masked`, `orders:read:unmasked`         | Retrieve order information, including recipient and delivery details.   | Sensitive Information. V2 and V3.                                                                                  |
| **Cancel Order**               | `orders:cancel`                                      | Cancel orders that have not yet been picked up by fulfillment.          | V2 and V3.                                                                                                         |
| **Create & Update Campaigns**  | `campaigns:create`, `campaigns:update`               | Create and update Campaigns (a template for sending gifts).             | V2 only.                                                                                                           |
| **Read Campaigns**             | `campaigns:read`                                     | Retrieve Campaigns with filtering and pagination.                       | V2 only.                                                                                                           |
| **Read Collections**           | `collections:read`                                   | Retrieve Collections and their budget ranges.                           | V2: list + budgets. V3: list and by-ID Collection resources. Products within a Collection require `products:read`. |
| **Read Products**              | `products:read`                                      | Read products, variants, brands, and tags.                              | Covers V2 Products & Variants, V3 Products & Variants, and V3 Base Products (Swag catalog).                        |
| **Create Recipients**          | `recipients:create`                                  | Add new recipients to the account roster.                               | `POST /v2/recipients`.                                                                                             |
| **Update / Delete Recipients** | `recipients:update`, `recipients:delete`             | Update, override, or delete recipients in the account roster.           |                                                                                                                    |
| **Read Recipients**            | `recipients:read:masked`, `recipients:read:unmasked` | Retrieve recipient information.                                         | Sensitive Information.                                                                                             |
| **Create Account**             | `accounts:create`                                    | Create accounts.                                                        | V2 and V3.                                                                                                         |
| **Read Account**               | `accounts:read`                                      | Retrieve account information.                                           | V2 and V3.                                                                                                         |
| **Read Billing Methods**       | `billingMethods:read`                                | Retrieve Billing Method details: remaining balance, status, expiration. | V3 only - introduced with the V3 Billing Methods API.                                                              |

### Data Privacy & PII Masking

To protect employee and recipient privacy, Snappy masks Personally Identifiable Information (PII) in API responses by default.
If a key does not have explicit permission to view sensitive data, fields are returned partially redacted. For example:

* **Email:** `j*******@e*****.com`
* **Name:** `J*** D***`
* **Phone:** `(***) ***-1234`
* **IDs:** `3****`
  To retrieve unmasked data, toggle the **"Expose Sensitive Information"** setting when generating the API key in the dashboard. This determines whether reads against PII-bearing endpoints resolve to the `:read:masked` or `:read:unmasked` permission tier.

### Creating an API Key

Snappy supports up to **100 active API keys** per Company.

1. Log in to your Snappy Dashboard at [https://login.snappy.com/login](https://login.snappy.com/login).
2. Navigate to **Sharing & Access** under **Company Settings** ([https://login.snappy.com/company-settings/general](https://login.snappy.com/company-settings/general)).
3. Scroll to **API Access** and enable API access for your organization if not already enabled.
4. Click **Generate Key**.
5. **Name your key.**
6. **Set Expiration:** Select your key rotation policy (keys can be set to expire in up to one year).
7. Check the mTLS checkbox if you are an Enterprise customer using enhanced network security.
8. **Assign Permissions:** Select the specific scopes this key will have access to.
9. **Configure Privacy & Security:** Toggle sensitive information access on or off depending on your PII requirements.
10. Click **Generate Key**.
11. **Copy the key immediately.** For security reasons, the secret key is never displayed again.

### Rotating a Key

To reset a compromised key or comply with your company's security policies, rotate keys without integration downtime:

1. Follow the **Creating an API Key** steps above to generate a new scoped key.
2. Update your application's environment variables with the new key.
3. Verify the new key is working in production.
4. Delete the old key from the Snappy Dashboard.
   This pattern lets you cut over with zero downtime - both keys remain valid until you delete the old one.

### The API Key Object

When you retrieve your API keys via the management endpoint, each key is returned as an object with the following fields:

| Field            | Type              | Description                                                                                                                              |
| :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | string            | Unique identifier for the API key.                                                                                                       |
| `name`           | string            | Display name assigned to the key at creation.                                                                                            |
| `expirationDate` | string (ISO 8601) | When the key will expire.                                                                                                                |
| `enforceMtls`    | boolean           | Whether Mutual TLS is enforced for requests using this key. See [Enterprise Security: Mutual TLS](#enterprise-security-mutual-tls-mtls). |
| `createdAt`      | string (ISO 8601) | When the key was created.                                                                                                                |

<Note>
  For security reasons, the secret key value itself is returned **only once** - at the moment of creation. It is never included in subsequent `GET` responses. If you lose your key, you'll need to rotate it.
</Note>

***

## Enterprise Security: Mutual TLS (mTLS)

For environments requiring strict network security (such as financial institutions or highly regulated microservices), Snappy offers Mutual TLS (mTLS).
In a standard API request, the client verifies the server's identity. With mTLS, the authentication goes both ways: Snappy verifies the client's SSL certificate, and the client verifies Snappy's SSL certificate. This guarantees a secure, encrypted communication channel and actively prevents man-in-the-middle attacks.

### mTLS Base URL

mTLS requests go to a dedicated base URL with a separate certificate-validating endpoint:

```text theme={null}
https://mtls-api.snappy.com/public-api
```

All V2 and V3 endpoints are accessible at this base URL - append `/v2/...` or `/v3/...` as you would on the standard URL.

### Setting up mTLS

1. Contact your Snappy account representative to request mTLS provisioning for your organization.
2. Snappy issues your client SSL certificate.
3. When generating an API key in the dashboard, check the **mTLS** checkbox to enforce mutual authentication for requests using that key.
4. Configure your HTTP client to present the issued certificate when making requests to `mtls-api.snappy.com`.

<Tip>
  Static API keys cover all standard integrations. Enable mTLS in addition to your API key only if your security policy requires certificate-based mutual authentication.
</Tip>