X-Api-Key. These endpoints are restricted to Company owners and tools admins.
For programmatic key management from a backend service or CI/CD pipeline (using an existing API key for auth), see the V2 API Keys endpoints. V2 and V3 serve different use cases - V2 for service-to-service automation, V3 for human-operator dashboard flows.
Authentication
V3 API Keys endpoints use a dashboard user JWT in theAuthorization header:
Snappy-Company-Id to select the target Company. Only Company owners and tools admins can call these endpoints - other users will receive 403 Forbidden.
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
Restricted to owner-level dashboard users
Unlike V2, the V3 endpoints don’t accept anX-Api-Key. Authentication requires a valid dashboard user session token, and the user must be a Company owner or tools admin. Standard dashboard users will receive 403.
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 keyspage[number] / page[size].
Create an API key
204 No Content on success.