Create API key

curl --request POST \
  --url https://api.snappy.com/public-api/v2/authentication/apiKeys \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "My API",
  "expirationInDays": 90,
  "enforceMtls": false
}
'

{
  "id": "abc123456",
  "expirationDate": "2022-12-06T09:50:38.536Z",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "enforceMtls": true,
  "name": "My API key",
  "companyId": "abc12345678",
  "apiKey": "abc123456abc123454542343",
  "permissions": [],
  "accountsAccess": {
    "ids": [
      "<string>"
    ]
  }
}

API Keys

Create API key

Use this endpoint to programmatically create a new API key for your Company. Use this when rotating keys, provisioning a key for a new integration, or spinning up a scoped key for a specific Account from a backend service or automation pipeline.

Required fields

name - display name of the API key (must be unique within the Company)

Optional fields

expirationInDays - number of days until the key expires. Accepted values: 30, 60, 90, 180, 365. Default: 90.
enforceMtls - when true, requests with this key must use mTLS. Default: false.
permissions - array of permission scopes the new key should have. See the permission reference.
accountIds - array of Account IDs the key should be scoped to. Omit for all-Accounts access.

Behavior Notes

The API key secret is visible only in this response. The apiKey field in the response body is your one and only chance to capture the secret value - store it securely. After this response, only metadata is retrievable.
Permission inheritance. Keys created via the API can only have the same permissions as the calling key, or a more restrictive subset. Attempts to grant permissions the calling key doesn’t have are rejected.
Max 100 active API keys per Company. Delete an existing key before creating the 101st.

Permissions

Authenticated via Authorization: Bearer <dashboard user JWT>. Only Company owners and tools admins have access.

POST

authentication

apiKeys

Create API key

curl --request POST \
  --url https://api.snappy.com/public-api/v2/authentication/apiKeys \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "My API",
  "expirationInDays": 90,
  "enforceMtls": false
}
'

{
  "id": "abc123456",
  "expirationDate": "2022-12-06T09:50:38.536Z",
  "createdAt": "2022-12-06T09:50:38.536Z",
  "enforceMtls": true,
  "name": "My API key",
  "companyId": "abc12345678",
  "apiKey": "abc123456abc123454542343",
  "permissions": [],
  "accountsAccess": {
    "ids": [
      "<string>"
    ]
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients.

Getting Your API Key

Create an API Key: Use the POST /v2/authentication/apiKeys endpoint to generate a new API key
Set Expiration: Choose from 30, 60, 90, or 180 days (default: 90 days)
Optional mTLS: Enable mutual TLS for enhanced security
Name Your Key: Provide a descriptive name for easy identification

Using Your API Key

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_24_CHARACTER_API_KEY

API Key Management

Maximum Keys: Up to 3 active API keys per company
Rotation: Delete old keys before creating new ones when at the limit
Security: Keys are hashed and cannot be retrieved after creation

Enhanced Security (mTLS)

For production environments, enable mutual TLS authentication:

Set enforceMtls: true when creating the API key
Contact support to obtain your client certificates
Use the mTLS endpoint: https://mtls-api.snappy.com/public-api

Headers

Request-Source

enum<string>

Source of the request

Available options:

api_native,

api_zapier,

api_salesforce,

api_ftp,

api_make

Example:

"api_native"

Query Parameters

companyId

string

Company ID

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"12345678"

Body

application/json

Create API key request body.

name

string

required

The name of the API key. The name is used to identify the API key. The name must be unique.

Minimum string length: 1

Example:

"My API"

expirationInDays

number | null

default:90

API key expiration period in days. Valid values: 30, 60, 90, 180, 365. Default: 90 days.

Required range: 0.00069 <= x <= 365

enforceMtls

boolean

default:false

If true, the API key will be enforced to use mTLS. If false, the API key will not be enforced to use mTLS. The default value is false.

Example:

true

permissions

enum<string>[]

The permissions of the API key.

Available options:

gifts:create,

gifts:create:demo,

gifts:update,

gifts:read:unmasked,

gifts:read:masked,

orders:create,

orders:cancel,

orders:read:unmasked,

orders:read:masked,

campaigns:create,

campaigns:update,

campaigns:read,

collections:read,

products:read,

recipients:create,

recipients:update,

recipients:read:unmasked,

recipients:read:masked,

recipients:delete,

accounts:create,

accounts:read,

billingMethods:read

accountIds

string[]

Response

API key object.

string

required

The API key id

Example:

"abc123456"

expirationDate

string | null

required

The date the API key will expire. Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

createdAt

string

required

The date the API key was created. Date Format: YYYY-MM-DDThh:mm:ss.sZ.

Example:

"2022-12-06T09:50:38.536Z"

enforceMtls

boolean

required

If true, the API key will be enforced to use mTLS. If false, the API key will not be enforced to use mTLS.

Example:

true

name

string

required

The name of the API key

Example:

"My API key"

companyId

string

The company id

Example:

"abc12345678"

apiKey

string

The API key

Pattern: ^[a-fA-F0-9]{24}$

Example:

"abc123456abc123454542343"

permissions

enum<string>[]

The permissions of the API key.

Available options:

gifts:create,

gifts:create:demo,

gifts:update,

gifts:read:unmasked,

gifts:read:masked,

orders:create,

orders:cancel,

orders:read:unmasked,

orders:read:masked,

campaigns:create,

campaigns:update,

campaigns:read,

collections:read,

products:read,

recipients:create,

recipients:update,

recipients:read:unmasked,

recipients:read:masked,

recipients:delete,

accounts:create,

accounts:read,

billingMethods:read

accountsAccess

object

The accounts access of the API key.

Show child attributes

Last modified on June 17, 2026

Get API keys

Delete API key