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

# Update an API key

> Update key metadata (name, permissions, rate limits, active status).
The key value itself cannot be changed — create a new key instead.

**Requires Supabase JWT authentication.**




## OpenAPI

````yaml patch /v1/api-keys/{keyId}
openapi: 3.1.0
info:
  title: TalkPilot API
  version: 1.0.0
  description: >
    The TalkPilot API allows you to programmatically manage your call center
    agents,

    employees, forwarding slots, knowledge base, and more.


    ## Authentication


    All API requests require an API key passed via the `X-API-Key` header:


    ```

    X-API-Key: tp_live_abc123def456...

    ```


    An API key can reach every organization its creator is a member of (see

    `GET /v1/organization`) and can be restricted to specific agents and
    permissions.

    Create and manage keys in the TalkPilot Dashboard under **Settings > API**

    (Dev-Admin only).


    ## Rate Limiting


    Default limits per API key: **60 requests/minute** and **1,000
    requests/hour**

    (both enforced, both configurable per key).


    Rate limit headers are included in every response to a request authenticated

    with an API key (Dashboard JWT requests are not rate limited):

    - `X-RateLimit-Limit` — Max requests per minute

    - `X-RateLimit-Remaining` — Remaining requests in the current minute window

    - `X-RateLimit-Reset` — Unix timestamp roughly 60 seconds in the future


    When rate limited, the API returns `429 Too Many Requests` with
    `Retry-After: 60`

    (minute window) or `Retry-After: 3600` (hour window).


    ## Pagination


    List endpoints support pagination via query parameters:

    - `page` — Page number (default: 1)

    - `limit` — Items per page (default: 20, max: 100)


    Paginated responses include a `pagination` object with `page`, `limit`,
    `total`, and `pages`.


    ## Error Format


    All errors follow a consistent format:


    ```json

    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Human-readable description",
        "details": [{ "field": "name", "message": "Required" }],
        "request_id": "req_abc123"
      }
    }

    ```
  contact:
    name: TalkPilot Support
    email: support@talkpilot.io
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.talkpilot.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Health
    description: API health and status
  - name: Agents
    description: Manage AI agent configurations
  - name: Workflow
    description: Multi-state conversation flow of an agent
  - name: Tools
    description: Manage agent tools (HTTP requests, call transfers, etc.)
  - name: Employees
    description: Manage employees linked to agents
  - name: Contacts
    description: >-
      Customer contacts (customer_database) per agent — the voice agent
      recognises callers and greets them by name or tag from here
  - name: Forwarding Slots
    description: Manage call forwarding slot assignments
  - name: Knowledge Base
    description: Manage agent knowledge base documents
  - name: Calls
    description: Read call records and transcripts
  - name: Organization
    description: Organization-level settings
  - name: API Keys
    description: Manage API keys (Dashboard JWT auth only; dev_admin)
paths:
  /v1/api-keys/{keyId}:
    patch:
      tags:
        - API Keys
      summary: Update an API key
      description: |
        Update key metadata (name, permissions, rate limits, active status).
        The key value itself cannot be changed — create a new key instead.

        **Requires Supabase JWT authentication.**
      operationId: updateApiKey
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyUpdate'
            examples:
              deactivate:
                summary: Deactivate a key
                value:
                  is_active: false
              changePermissions:
                summary: Restrict to read-only
                value:
                  name: n8n Read-Only
                  permissions:
                    - agents:read
                    - employees:read
                    - calls:read
      responses:
        '200':
          description: Updated API key info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []
components:
  schemas:
    ApiKeyUpdate:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        allowed_agent_ids:
          type:
            - array
            - 'null'
          items:
            type: string
            format: uuid
        rate_limit_per_minute:
          type: integer
          minimum: 1
          maximum: 600
        rate_limit_per_hour:
          type: integer
          minimum: 1
          maximum: 10000
        is_active:
          type: boolean
    ApiKeyInfo:
      type: object
      description: API key metadata (the actual key value is never returned after creation)
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        key_prefix:
          type: string
          description: First 10 characters of the key for identification
          example: tp_live_a1
        organization_id:
          type: string
          format: uuid
          description: Home organization of the key (key management only)
        organization_name:
          type:
            - string
            - 'null'
          description: Name of the home organization (list endpoint only)
        created_by_email:
          type:
            - string
            - 'null'
          description: Email of the creator; null for legacy keys (list endpoint only)
        is_own:
          type: boolean
          description: Whether the requesting user created this key (list endpoint only)
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        allowed_agent_ids:
          type:
            - array
            - 'null'
          items:
            type: string
            format: uuid
          description: Restrict key to specific agents (null = all agents in organization)
        rate_limit_per_minute:
          type: integer
        rate_limit_per_hour:
          type: integer
        is_active:
          type: boolean
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Permission:
      type: string
      enum:
        - agents:read
        - agents:write
        - employees:read
        - employees:write
        - tools:read
        - tools:write
        - forwarding:read
        - forwarding:write
        - kb:read
        - kb:write
        - calls:read
        - organization:read
        - organization:write
        - contacts:read
        - contacts:write
      description: |
        Available permissions:
        - `agents:read` — List and view agent configurations
        - `agents:write` — Update agent settings
        - `employees:read` — List and view employees
        - `employees:write` — Create, update, delete employees
        - `tools:read` — List and view agent tools
        - `tools:write` — Create, update, delete tools
        - `forwarding:read` — List forwarding slots
        - `forwarding:write` — Create, update, delete forwarding slots
        - `kb:read` — List and view knowledge base documents
        - `kb:write` — Create, update, delete KB documents
        - `calls:read` — List and view call records
        - `organization:read` — View organization settings
        - `organization:write` — Update organization settings
        - `contacts:read` — List and view contacts (customer database)
        - `contacts:write` — Create, update, delete contacts
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - UNAUTHORIZED
                - FORBIDDEN
                - AGENT_NOT_ACCESSIBLE
                - NOT_FOUND
                - CONFLICT
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
            request_id:
              type: string
  responses:
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
              request_id: req_abc123
    Forbidden:
      description: >
        Insufficient permissions (`FORBIDDEN`), or the agent is outside the
        key's

        `allowed_agent_ids` (`AGENT_NOT_ACCESSIBLE`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingPermission:
              value:
                error:
                  code: FORBIDDEN
                  message: 'API key lacks required permission: agents:write'
                  request_id: req_abc123
            agentNotAccessible:
              value:
                error:
                  code: AGENT_NOT_ACCESSIBLE
                  message: API key does not have access to this agent
                  request_id: req_abc123
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Agent not found
              request_id: req_abc123
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for external access. Format: `tp_live_<32-hex-chars>`.
        Create keys in the TalkPilot Dashboard under Settings > API.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Supabase JWT token (for Dashboard-only endpoints like API key
        management)

````