> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naturalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create API Key

> Creates a new API key for the current account. The full key is returned
only once in the response and is never stored or retrievable again.
The key creator can only grant scopes (permissions) that they themselves hold.
Requires `api_keys:manage` permission.




## OpenAPI

````yaml POST /api/api-keys
openapi: 3.1.0
info:
  title: Naturalead API Keys API
  version: 1.0.0
  description: >
    API for managing programmatic API keys in the Naturalead platform.

    All endpoints require API key authentication and are scoped to the caller's
    account.
servers:
  - url: '{baseUrl}'
    description: API server
    variables:
      baseUrl:
        default: http://localhost:3001
security:
  - BearerAuth: []
tags:
  - name: API Keys
    description: API key lifecycle management (create, list, revoke, rotate, delete)
paths:
  /api/api-keys:
    post:
      tags:
        - API Keys
      summary: Create API key
      description: >
        Creates a new API key for the current account. The full key is returned

        only once in the response and is never stored or retrievable again.

        The key creator can only grant scopes (permissions) that they themselves
        hold.

        Requires `api_keys:manage` permission.
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Human-readable name for the key
                  example: Production CRM sync
                scopes:
                  type: array
                  items:
                    type: string
                  description: |
                    RBAC permissions to grant to this key. Must be a subset of
                    the creator's own permissions.
                  example:
                    - leads:view
                    - leads:import
                    - conversations:view
                environment:
                  type: string
                  enum:
                    - live
                    - test
                  description: Key environment (affects key prefix nl_live_ or nl_test_)
                expiresAt:
                  type: string
                  format: date-time
                  description: Optional expiration date (must be in the future)
              required:
                - name
                - scopes
                - environment
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  apiKey:
                    $ref: '#/components/schemas/ApiKey'
                  fullKey:
                    type: string
                    description: >
                      The complete API key. This is shown only once and cannot
                      be

                      retrieved later. Store it securely.
                    example: nl_live_a1b2c3d4e5f6...
                required:
                  - apiKey
                  - fullKey
        '400':
          description: |
            Validation error. Possible reasons: missing name, empty scopes,
            invalid environment, expired date, maximum keys reached, or
            attempting to grant permissions not held by the creator.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ApiKey:
      type: object
      properties:
        _id:
          type: string
          description: Unique key identifier
        accountId:
          type: string
          description: Account this key belongs to
        name:
          type: string
          description: Human-readable key name
        keyPrefix:
          type: string
          description: Key prefix (e.g. nl_live_ or nl_test_)
        keyHint:
          type: string
          description: Last 4 characters of the key for identification
        scopes:
          type: array
          items:
            type: string
          description: RBAC permissions granted to this key
        environment:
          type: string
          enum:
            - live
            - test
        status:
          type: string
          enum:
            - active
            - revoked
            - expired
        expiresAt:
          type: string
          format: date-time
          nullable: true
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - _id
        - name
        - keyPrefix
        - keyHint
        - scopes
        - environment
        - status
        - createdAt
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token using an API key (format nl_live_* or nl_test_*)

````