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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Create API key

> Create a new API key. For service keys, pass keyType:"service". Optionally scope to specific projects via projectIds (ADMIN on each). Omit projectIds for full org access. Pass assignedToUserId to mint the key for another member, and permissionMode:"restricted" with a permissions list to grant exactly those permissions. Minting a service key or a key for another member requires organization admin rights. The plaintext token is returned once — store it securely.



## OpenAPI

````yaml POST /api/api-keys
openapi: 3.1.0
info:
  title: LangWatch API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/api-keys:
    post:
      summary: Create an API key
      description: >-
        Create a new API key. For service keys, pass keyType:"service".
        Optionally scope to specific projects via projectIds (ADMIN on each).
        Omit projectIds for full org access. Pass assignedToUserId to mint the
        key for another member, and permissionMode:"restricted" with a
        permissions list to grant exactly those permissions. Minting a service
        key or a key for another member requires organization admin rights. The
        plaintext token is returned once — store it securely.
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyType:
                  type: string
                  enum:
                    - personal
                    - service
                  default: personal
                  description: >-
                    A personal key acts as the user who created it and needs
                    explicit bindings. A service key is not tied to a user.
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Human-readable name for this key
                description:
                  type: string
                  maxLength: 500
                expiresAt:
                  type: string
                  description: ISO 8601 timestamp after which the key stops working
                assignedToUserId:
                  type: string
                  minLength: 1
                  description: >-
                    Organization admins only: the member who owns the key and
                    whose access caps it. Defaults to the caller.
                permissionMode:
                  type: string
                  enum:
                    - all
                    - readonly
                    - restricted
                  description: >-
                    'all' and 'readonly' take their meaning from the bindings
                    alone; 'restricted' additionally requires an explicit
                    permissions list.
                  default: all
                permissions:
                  type: array
                  items:
                    type: string
                  description: >-
                    Restricted mode only: the exact resource:action permissions
                    the key's CUSTOM bindings grant.
                bindings:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - ADMIN
                          - MEMBER
                          - VIEWER
                          - CUSTOM
                        description: >-
                          CUSTOM grants exactly the listed permissions and
                          requires permissionMode 'restricted'.
                      scopeType:
                        type: string
                        enum:
                          - ORGANIZATION
                          - TEAM
                          - PROJECT
                      scopeId:
                        type: string
                        minLength: 1
                    required:
                      - role
                      - scopeType
                      - scopeId
                  maxItems: 20
                  description: >-
                    What this key may do, and where. Required for a personal
                    key.
                projectIds:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  maxItems: 50
                  description: 'Service keys only: restricts the key to these projects'
              required:
                - name
      responses:
        '201':
          description: >-
            API key created. The token field contains the plaintext key — it is
            only shown once.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: >-
                      Plaintext API key token (sk-lw-...). Store securely —
                      shown only once.
                  apiKey:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
        '401':
          description: Invalid or missing API key token
        '403':
          description: >-
            Requested binding exceeds the creator's own permissions, or the
            scope does not belong to this organization
            (api_key_scope_violation); a service key or a key for another member
            was requested without organization admin rights
            (insufficient_permissions)
        '422':
          description: >-
            Validation error, for example a missing name or empty bindings
            (validation_error), or a name LangWatch reserves for its own keys
            (api_key_reserved_name)
      security:
        - admin_api_key: []
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.
    admin_api_key:
      type: http
      scheme: bearer
      description: >-
        Admin API key for organization-level operations (managing projects, API
        keys). Create one in Settings > API Keys or via POST /api/api-keys.
        Format: sk-lw-{id}_{secret}.

````