For dashboard-driven, interactive key management by Company owners or tools admins, see the V3 API Keys endpoints. V2 and V3 serve different use cases - V2 for service-to-service automation, V3 for human-operator dashboard flows.
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 secretapiKey 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, setenforceMtls: 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 for setup details.
How to Work with API Keys (V2)
List API keysapiKey value is never included.
Create an API key
204 No Content on success.