Snappy APIs are authenticated using scoped API keys passed in theDocumentation Index
Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
Use this file to discover all available pages before exploring further.
X-Api-Key header. OAuth2 is not used. Enterprise customers may optionally enable Mutual TLS (mTLS) for additional network-level security.
Authenticating Requests
To communicate with the Snappy API, you need an API key to authenticate your application. You must include your API key in the header of every request using the X-Api-Key header format:Although you must create your first API Key via the Snappy dashboard, you can programmatically manage (create, retrieve and delete) future keys using the API Keys endpoints
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. This means 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 (like gift statuses or catalog items) without the ability to spend budget or send gifts.
- Full Access: Allow an integration to create campaigns, generate orders, and manage users.
- Account-Level Access: Restrict a key so it can only operate within a specific sub-account rather than your entire company profile.
Each environment (Testing and Production) has its own set of API keys. Never use a Production key in your test environment or vice versa.
Available Scopes
Below is a breakdown of the available permissions you can assign to a key, along with the endpoints they unlock:| Permission Name | API Scope | Description | Associated Endpoints | Comment |
|---|---|---|---|---|
| Create & Update Gifts | gifts:creategifts:update | Can create or update gifts for recipients and notify them. | POST /gifts PATCH /gifts/ POST /gifts/ /expire | |
| Get Gifts | gifts:read:maskedgifts:read:unmasked | Can retrieve all gift information including recipients. | GET /gifts GET /gifts/ | Sensitive Information |
| Create a Demo Gift | gifts:create:demo | Can create a demo gift that you can share. | POST /gifts/demo | |
| Create an Order | orders:create | Can place an order by for an item. | POST /orders | Billable action |
| Get Orders | orders:read:maskedorders:read:unmasked | Can retrieve all gift information including recipients and delivery details. | GET /gifts/ (order, delivery) GET /gifts (order, delivery) POST /orders/addresses/validate GET /orders/addresses/autocomplete | Sensitive Information |
| Cancel Unprocessed Order | orders:cancel | Can cancel unprocessed orders. | POST /gifts/ /cancel | |
| Create & Update Campaigns | campaigns:createcampaigns:update | Can create and update campaigns. A Campaign is a template for sending gifts. | POST /campaigns PATCH /campaigns/ | |
| Get Campaigns | campaigns:read | Can get campaigns with flexible filtering and pagination options. | GET /campaigns GET /campaigns/ GET /campaigns/ /estimated-cost | |
| Get Collections & Budgets | collections:read | Can retrieve available collections based on budget, countries, and other filters. | GET /collections GET /collections/budgets | |
| Get Products | products:read | GET /collections/ /products GET /products/tags GET /products GET /products/ /variants GET /products/variants/ | ||
| Create Recipients | recipients:create | Can add new recipients to the account roster. | POST /recipients | |
| Update, Override & Delete Recipients | recipients:updaterecipients:delete | Can update, override details, or delete recipients in the account roster. | PATCH /recipients/ DELETE /recipients/ | |
| Get Recipients | recipients:read:maskedrecipients:read:unmasked | Can retrieve all recipient information. | GET /recipients GET /recipients/ | Sensitive Information |
| Create Account | accounts:create | Can create accounts. | POST /accounts | |
| Get Account | accounts:read | Can retrieve all account information. | GET /accounts GET /accounts/ |
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 the explicit permission to view sensitive data, fields will be returned partially redacted. For example:- Email: j*******@e*****.com
- Name: J*** D***
- Phone: (***) ***-1234
- IDs: 3****
Creating an API Key
Snappy supports up to 100 active API keys per company.- Log in to your Snappy Dashboard https://login.snappy.com/login.
- Navigate to Sharing & Access tab under the Company Settings page in the Snappy Dashboard (https://login.snappy.com/company-settings/general).
- Scroll down to the ‘API Access’ section 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 1 year).
- Check the mTLS checkbox if you are an Enterprise customer using enhanced network security.
- Assign Permissions: Select the specific APIs and scopes this key will have access to.
- Configure Privacy & Security: Toggle sensitive information on/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, you can easily rotate keys without integration downtime. Simply follow the steps above to generate a new scoped key, update your application’s environment variables with the new key, and then delete the compromised key from the Snappy Dashboard.The API Key Object
When you retrieve your API keys viaGET /authentication/apiKeys, 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 timestamp of when the key will expire |
enforceMtls | boolean | Whether Mutual TLS is enforced for requests using this key. See Enterprise Security: Mutual TLS below |
createdAt | string | ISO 8601 timestamp of when the key was created |
For security reasons, the secret key value itself is only returned once — at the moment of creation. It is never included in subsequent GET responses. If you lose your key, you will need to rotate it.