> ## 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 create a new API key from an authenticated dashboard session. Use this when an owner or tools admin needs to mint a key - for a new integration, for key rotation, or to scope access to specific Accounts. ###### 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). - `accountsAccess` - `{ scope: "all-accounts" | "specific-accounts", ids: [] }` to scope the key to specific Accounts. ###### Optional headers - `Snappy-Account-Id` - optional account scoping - `Snappy-Company-Id` - required for multi-company users to select the target Company ###### Behavior Notes - **The API key secret is visible only in this response.** Store it securely - it cannot be retrieved later. - **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 /v3/authentication/api-keys openapi: 3.0.3 info: title: Snappy Public API v3 version: 3.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. 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: Products description: >- Use these endpoints to retrieve products and tags for building catalog and browse experiences in your UI. - name: Collections description: >- Use these endpoints to retrieve products within curated collections for marketplace and browse experiences. - name: Variants description: >- Use these endpoints to retrieve variants, variant pricing, and country availability for orderable product SKUs. - name: Billing Methods description: >- A **Billing Method** is the funding source attached to an **Account** - for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit Card. Use these endpoints to retrieve billing method details such as remaining balance, status, and expiration. - name: Accounts description: >- An **Account** is a sub-entity within a **Company**, used to organize campaigns and gift sends. Use these endpoints to list, retrieve, and create accounts. - name: API Keys description: >- Use these endpoints to manage API keys for programmatic access. Key management requires company owner privileges. - name: Orders description: >- Use these endpoints to place, retrieve, cancel, and validate orders and shipping addresses. paths: /v3/authentication/api-keys: post: tags: - Api_keys summary: Create API key description: >- Use this endpoint to create a new API key from an authenticated dashboard session. Use this when an owner or tools admin needs to mint a key - for a new integration, for key rotation, or to scope access to specific Accounts. ###### 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). - `accountsAccess` - `{ scope: "all-accounts" | "specific-accounts", ids: [] }` to scope the key to specific Accounts. ###### Optional headers - `Snappy-Account-Id` - optional account scoping - `Snappy-Company-Id` - required for multi-company users to select the target Company ###### Behavior Notes - **The API key secret is visible only in this response.** Store it securely - it cannot be retrieved later. - **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. parameters: - schema: type: string description: Optional account identifier for swag validation/filtering. example: acc123456 required: false description: Optional account identifier for swag validation/filtering. name: snappy-account-id in: header - schema: type: string description: Optional company identifier for swag validation/filtering. example: cmp123456 required: false description: Optional company identifier for swag validation/filtering. name: snappy-company-id in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyV3Body' responses: '200': description: Created API key including the secret. content: application/json: schema: $ref: '#/components/schemas/SingleApiKeyResponseV3' '400': description: Bad Request - Invalid request body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Forbidden - Owner privileges required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' security: - BearerTokenAuthentication: [] - ApiKeyAuthentication: [] components: schemas: CreateApiKeyV3Body: type: object properties: name: type: string minLength: 1 description: The name of the API key. Must be unique within the company. example: My API expirationInDays: type: number nullable: true minimum: 0.00069 maximum: 365 default: 90 description: 'API key expiration period in days. Default: 90 days.' enforceMtls: $ref: '#/components/schemas/EnforceMtlsV3' permissions: $ref: '#/components/schemas/ApiKeyPermissionsV3' accountIds: type: array items: type: string required: - name additionalProperties: false description: Create API key request body. SingleApiKeyResponseV3: type: object properties: data: $ref: '#/components/schemas/ApiKeyWithSecretV3' required: - data description: JSON:API single-resource envelope for a created API key. ErrorResponseV3: type: object properties: message: type: string description: Human-readable error message. example: Product not found. errorCode: type: string description: Structured error code. example: 404_PROD_001 errors: type: array items: type: object properties: message: type: string example: Product with id 'q1w2e3r4t5' was not found path: type: string description: Dot-separated path to the field that caused the error. example: pathParameters.productId errorCode: type: string example: 404_PROD_001 required: - message - path description: Optional field-level error details. required: - message - errorCode description: Standard v3 error envelope. EnforceMtlsV3: type: boolean default: false description: If true, the API key will be enforced to use mTLS. example: false ApiKeyPermissionsV3: 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 - products:read:prices - 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. ApiKeyWithSecretV3: allOf: - $ref: '#/components/schemas/ApiKeyV3' - type: object properties: apiKey: type: string pattern: ^[a-fA-F0-9]{24}$ description: The API key secret. Returned only on create. example: abc123456abc123454542343 required: - apiKey description: API key object including the secret returned on create. ApiKeyV3: 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: Whether the API key requires mTLS. example: false name: type: string description: The name of the API key. example: My API key companyId: type: string description: The company id. example: abc12345678 permissions: $ref: '#/components/schemas/ApiKeyPermissionsV3' accountsAccess: $ref: '#/components/schemas/AccountsAccessV3' required: - id - expirationDate - enforceMtls - name description: API key object (without secret). AccountsAccessV3: 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: BearerTokenAuthentication: type: http scheme: bearer bearerFormat: JWT description: >- ## User Bearer Authentication Use a dashboard user JWT in the `Authorization` header when managing API keys from the Snappy dashboard: ``` Authorization: Bearer YOUR_JWT ``` For multi-company users, also pass `Snappy-Company-Id` to select the target company. ApiKeyAuthentication: type: apiKey in: header name: X-Api-Key description: |- ## Company Level Authentication Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_API_KEY ``` ````