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

# Create pod API key

> Mint an API key scoped to this pod. The key can only read and send from the pod's inboxes and can never manage pods or reach another pod's data. The full `token` is returned once, here — store it securely, it cannot be retrieved again. Requires an account-wide key (a pod-scoped key cannot mint keys).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/pods/{id}/api-keys
openapi: 3.0.3
info:
  title: OpenMail API
  description: >-
    Email infrastructure API for AI agents. Create inboxes, send and receive
    email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.openmail.sh
security:
  - bearerAuth: []
tags:
  - name: pods
    description: Isolated sub-accounts for your end users or tenants
  - name: inboxes
    description: Email inboxes and their webhook configuration
  - name: messages
    description: Sending and listing messages
  - name: threads
    description: Conversation threads and read status
  - name: attachments
    description: Downloading and extracting text from attachments
paths:
  /v1/pods/{id}/api-keys:
    post:
      tags:
        - pods
      summary: Create pod API key
      description: >-
        Mint an API key scoped to this pod. The key can only read and send from
        the pod's inboxes and can never manage pods or reach another pod's data.
        The full `token` is returned once, here — store it securely, it cannot
        be retrieved again. Requires an account-wide key (a pod-scoped key
        cannot mint keys).
      operationId: createPodApiKey
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
          description: Pod ID or your own `clientId`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Human-readable label to identify the key later.
                  nullable: true
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                description: API key created
                allOf:
                  - $ref: '#/components/schemas/ApiKeyWithToken'
        '403':
          description: The authenticating key is pod-scoped and cannot mint keys
          content:
            application/json:
              schema:
                description: The authenticating key is pod-scoped and cannot mint keys
                allOf:
                  - $ref: '#/components/schemas/Error'
        '404':
          description: Pod not found
          content:
            application/json:
              schema:
                description: Pod not found
                allOf:
                  - $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The pod already has the maximum number of active keys
            (`api_key_limit_reached`)
          content:
            application/json:
              schema:
                description: >-
                  The pod already has the maximum number of active keys
                  (`api_key_limit_reached`)
                allOf:
                  - $ref: '#/components/schemas/Error'
components:
  schemas:
    ApiKeyWithToken:
      type: object
      additionalProperties: true
      description: >-
        An API key plus its raw `token`. The token is returned only once, at
        creation, and is never retrievable again.
      allOf:
        - $ref: '#/components/schemas/ApiKey'
      properties:
        token:
          type: string
          description: >-
            The secret API key. Store it securely — it is shown only once and
            cannot be retrieved later.
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    ApiKey:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: OpenMail API key ID
        name:
          type: string
          description: Human-readable label for the key, if set.
          nullable: true
        podId:
          type: string
          description: >-
            ID of the pod this key is scoped to. A key can only access resources
            in this pod.
          nullable: true
        tokenPrefix:
          type: string
          description: Non-secret leading characters of the token, to help you identify it.
        last4:
          type: string
          description: Last 4 characters of the token, shown alongside the prefix.
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          description: When the key last authenticated a request, or null if never used.
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````