Snappy API Authentication: API Keys, Scopes & mTLS

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.

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.

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.
Enterprise mTLS (optional)	API key + client certificate	`X-Api-Key` + TLS cert	Use the mTLS base URL - see Enterprise Security: Mutual TLS.

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:

X-Api-Key: YOUR_API_KEY

Example request against a V3 endpoint:

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:

curl --request GET \
  --url https://api.snappy.com/public-api/v2/accounts \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'accept: application/json'

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 - see Managing API Keys below.

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.

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.

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

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

Always assign the minimum required permissions necessary for your integration to function.

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.

Log in to your Snappy Dashboard at https://login.snappy.com/login.
Navigate to Sharing & Access under Company Settings (https://login.snappy.com/company-settings/general).
Scroll to API Access and enable API access for your organization if not already enabled.
Click Generate Key.
Name your key.
Set Expiration: Select your key rotation policy (keys can be set to expire in up to one year).
Check the mTLS checkbox if you are an Enterprise customer using enhanced network security.
Assign Permissions: Select the specific scopes this key will have access to.
Configure Privacy & Security: Toggle sensitive information access on or off depending on your PII requirements.
Click Generate Key.
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:

Follow the Creating an API Key steps above to generate a new scoped key.
Update your application’s environment variables with the new key.
Verify the new key is working in production.
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.
`createdAt`	string (ISO 8601)	When the key was created.

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.

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:

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

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

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.

Welcome

Start building

Our API Standards

Migrating to V3

Webhooks & Events

Snappy API Authentication: API Keys, Scopes & mTLS

Authentication at a glance

Authenticating Requests

Base URLs

Optional Scoping Header (V3)

Managing API Keys

API Permissions & Key Management

Overview

Available Scopes

Data Privacy & PII Masking

Creating an API Key

Rotating a Key

The API Key Object

Enterprise Security: Mutual TLS (mTLS)

mTLS Base URL

Setting up mTLS

​Authentication at a glance

​Authenticating Requests

​Base URLs

​Optional Scoping Header (V3)

​Managing API Keys

​API Permissions & Key Management

​Overview

​Available Scopes

​Data Privacy & PII Masking

​Creating an API Key

​Rotating a Key

​The API Key Object

​Enterprise Security: Mutual TLS (mTLS)

​mTLS Base URL

​Setting up mTLS

Authentication at a glance

Authenticating Requests

Base URLs

Optional Scoping Header (V3)

Managing API Keys

API Permissions & Key Management

Overview

Available Scopes

Data Privacy & PII Masking

Creating an API Key

Rotating a Key

The API Key Object

Enterprise Security: Mutual TLS (mTLS)

mTLS Base URL

Setting up mTLS