> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/pages/authentication-and-security#available-scopes). - `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 `. Only Company owners and tools admins have access. ## OpenAPI ````yaml post /v2/authentication/apiKeys openapi: 3.0.0 info: title: Snappy Public API version: 2.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. In just 3 simple steps you can start sending gifts today: pull the relevant campaign, send gifts to your recipients and track gift statuses. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Authentication description: >- API keys authenticate requests to the Snappy API. Use these endpoints to list active keys for your Company, create new keys, or delete keys you no longer need. - name: Accounts description: >- An **Account** is a sub-entity that lives within a **Company**. Accounts are used to separate and organize your company's campaigns and gift sends for different teams, departments or budget owners. - name: Campaigns description: >- A **Campaign** is the primary organizational object used to configure and send a batch of gifts. It acts as a template for all the settings of a single gifting initiative, including the target **Recipient** list, the selected **Collection** or **product**, the budget, branding, and notification messages. - name: Collections description: >- A **Collection** is a curated catalog of gift items tailored to a specific theme, budget range, and audience (e.g., "Birthday Gifts Under $50"). The gift recipient then chooses their preferred item directly from this collection. Use these endpoints to: - Get available collections based on budget and country requirements - Retrieve budget ranges for specific collections - Access collection details and products Please note: Swag collections can only be retrieved by specifying the accountId in the request. - name: Products & Variants description: >- Use these endpoints to search for and retrieve products and variants (including by collection and budget), and to list product tags for building catalog and filtering experiences in your UI. - name: Gifts description: >- A **Gift** is the core transactional object in the Snappy system. It represents the entire gifting experience for a **Recipient** within a **Campaign**, from initial creation to final delivery. The **Gift** object tracks the status and details through each stage of its lifecycle: 1. **Creation:** The gift is initiated and associated with a recipient and campaign. 2. **Notification:** The recipient is notified about their gift via email or other channels. 3. **Selection:** The recipient selects a specific product from the gift collection (if applicable). 4. **Order Generation:** An order is created based on the selected product and the recipient's shipping address. 5. **Delivery:** The physical product is shipped and its delivery status is tracked to completion. - name: Orders description: >- Endpoints for programmatically claiming gifts (ordering on behalf of recipients), cancelling orders before they ship, and validating or autocompleting shipping addresses as part of your checkout or fulfillment flow. - name: Recipients description: A **Recipient** is the end-user who receives a **Gift**. paths: /v2/authentication/apiKeys: post: tags: - API Keys summary: Create API key description: >- 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](/pages/authentication-and-security#available-scopes). - `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 `. Only Company owners and tools admins have access. operationId: createApiKey parameters: - schema: type: string pattern: ^[A-Za-z0-9]{8,}$ description: Company ID example: '12345678' required: false description: Company ID name: companyId in: query - schema: $ref: '#/components/schemas/RequestSourceHeader' required: false description: Source of the request name: Request-Source in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/CreateApiKey200Response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiError' - example: status: 401 errorCode: 401001 message: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiError' - example: status: 403 errorCode: 403001 message: Forbidden '404': description: Not Found content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiError' - example: status: 404 errorCode: 404001 message: Not Found security: - CompanyLevelAuthentication: [] - BearerAuthentication: [] components: schemas: RequestSourceHeader: type: string enum: - api_native - api_zapier - api_salesforce - api_ftp - api_make description: Source of the request example: api_native CreateApiKeyBody: type: object properties: name: type: string minLength: 1 description: |- The name of the API key. The name is used to identify the API key. The name must be unique. example: My API expirationInDays: type: number nullable: true minimum: 0.00069 maximum: 365 default: 90 description: |- API key expiration period in days. Valid values: 30, 60, 90, 180, 365. Default: 90 days. enforceMtls: $ref: '#/components/schemas/EnforceMtls' permissions: $ref: '#/components/schemas/ApiKeyPermissions' accountIds: type: array items: type: string required: - name additionalProperties: false description: Create API key request body. example: name: My API expirationInDays: 90 enforceMtls: false CreateApiKey200Response: type: object properties: id: type: string description: The API key id example: abc123456 expirationDate: type: string nullable: true description: >- The date the API key will expire. Date Format: YYYY-MM-DDThh:mm:ss.sZ. example: '2022-12-06T09:50:38.536Z' createdAt: type: string description: >- The date the API key was created. Date Format: YYYY-MM-DDThh:mm:ss.sZ. example: '2022-12-06T09:50:38.536Z' enforceMtls: type: boolean description: |- 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: type: string description: The name of the API key example: My API key companyId: type: string description: The company id example: abc12345678 apiKey: type: string pattern: ^[a-fA-F0-9]{24}$ description: The API key example: abc123456abc123454542343 permissions: $ref: '#/components/schemas/ApiKeyPermissions' accountsAccess: $ref: '#/components/schemas/AccountsAccess' required: - id - expirationDate - createdAt - enforceMtls - name description: API key object. ApiError: type: object properties: status: type: integer description: The HTTP status code. example: 400 errorCode: anyOf: - type: number - type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 10000 message: type: string description: The error message. example: Unauthorized errors: type: array items: type: object properties: path: type: string description: The path of the field that caused the error. example: body.recipients.0.email message: type: string description: The error message. example: Invalid email. errorCode: anyOf: - type: number - type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 10000 required: - path - message - errorCode description: >- An array of client errors. This field is being returned only for errors the client should fix, usually with status code 400. required: - status - errorCode - message description: Standard API error response with optional client error details example: status: 400 errorCode: 400001 message: Bad Request EnforceMtls: type: boolean default: false description: |- 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 ApiKeyPermissions: type: array items: type: string enum: - 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 description: The permissions of the API key. AccountsAccess: type: object properties: scope: type: string enum: - all-accounts - specific-accounts ids: type: array items: type: string required: - scope - ids description: The accounts access of the API key. securitySchemes: CompanyLevelAuthentication: type: apiKey in: header name: X-Api-Key description: > ## Company Level Authentication Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ### Getting Your API Key 1. **Create an API Key**: Use the `POST /v2/authentication/apiKeys` endpoint to generate a new API key 2. **Set Expiration**: Choose from 30, 60, 90, or 180 days (default: 90 days) 3. **Optional mTLS**: Enable mutual TLS for enhanced security 4. **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: 1. Set `enforceMtls: true` when creating the API key 2. Contact support to obtain your client certificates 3. Use the mTLS endpoint: `https://mtls-api.snappy.com/public-api` BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: >- Bearer authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ````