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

# Rotate a organization API key

> Requires the `api_keys:manage` secret-key scope.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/organizations/{organizationId}/api-keys/{keyId}/rotations
openapi: 3.1.0
info:
  title: Foil API
  version: '2026-03-25'
  description: >-
    Customer-facing Foil server APIs for sessions, visitor fingerprints,
    organizations, and API keys.
servers:
  - url: https://api.usefoil.com
    description: Production
security: []
tags:
  - name: Sessions
    description: Durable session readback endpoints.
  - name: Visitor fingerprints
    description: Durable visitor fingerprint readback endpoints.
  - name: Organizations
    description: Organization lifecycle endpoints.
  - name: API Keys
    description: Organization API key lifecycle endpoints.
  - name: Gate
    description: >-
      Registry, organization-owned services, signup sessions, agent tokens, and
      dashboard login sessions.
  - name: Gate Webhooks
    description: Outbound Gate webhook delivery contracts.
  - name: Webhooks
    description: Manage webhook endpoints, subscriptions, and outgoing event delivery.
  - name: Events
    description: Inspect organization events and their webhook delivery attempts.
paths:
  /v1/organizations/{organizationId}/api-keys/{keyId}/rotations:
    post:
      tags:
        - API Keys
      summary: Rotate a organization API key
      description: Requires the `api_keys:manage` secret-key scope.
      operationId: rotateOrganizationApiKey
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/OrganizationId'
            example: org_f6m39y94nh6fs513q03skj929c
        - name: keyId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ApiKeyId'
            example: key_6cw04zdmetw8t5rsdppadhper0
      responses:
        '201':
          description: Rotated API key response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedApiKeyResponse'
                example:
                  data:
                    object: api_key
                    id: key_6cw04zdmetw8t5rsdppadhper0
                    type: publishable
                    environment: live
                    name: Acme Growth Workspace
                    status: active
                    allowed_origins:
                      - https://app.acme.co/signup
                    scopes:
                      - '*'
                    rate_limit: 1
                    key_preview: FOIL_SAMPLE_KEY
                    display_key: FOIL_SAMPLE_KEY
                    revealed_key: FOIL_SAMPLE_KEY
                    last_used_at: '2026-03-24T20:00:05.000Z'
                    created_at: '2026-03-24T20:00:00.000Z'
                    rotated_at: '2026-03-24T20:00:05.000Z'
                    revoked_at: '2026-03-24T20:00:05.000Z'
                    grace_expires_at: '2026-03-24T20:00:05.000Z'
                  meta:
                    request_id: req_cf147349a4134208aebb8c70e25fb7e1
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
                example:
                  error:
                    code: request.validation_failed
                    message: Observation payload failed validation.
                    status: 1
                    retryable: true
                    request_id: req_cf147349a4134208aebb8c70e25fb7e1
                    docs_url: https://app.acme.co/signup
                    details:
                      fields:
                        - name: Acme Growth Workspace
                          issue: required
                          expected: string
                          received: any_of
                      allowed_values:
                        - verified
                      header_name: x-forwarded-for
                      parameter_set: browser_fingerprint
                      next_action: retry
        '403':
          description: Organization access denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
                example:
                  error:
                    code: request.validation_failed
                    message: Observation payload failed validation.
                    status: 1
                    retryable: true
                    request_id: req_cf147349a4134208aebb8c70e25fb7e1
                    docs_url: https://app.acme.co/signup
                    details:
                      fields:
                        - name: Acme Growth Workspace
                          issue: required
                          expected: string
                          received: any_of
                      allowed_values:
                        - verified
                      header_name: x-forwarded-for
                      parameter_set: browser_fingerprint
                      next_action: retry
        '404':
          description: API key not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
                example:
                  error:
                    code: request.validation_failed
                    message: Observation payload failed validation.
                    status: 1
                    retryable: true
                    request_id: req_cf147349a4134208aebb8c70e25fb7e1
                    docs_url: https://app.acme.co/signup
                    details:
                      fields:
                        - name: Acme Growth Workspace
                          issue: required
                          expected: string
                          received: any_of
                      allowed_values:
                        - verified
                      header_name: x-forwarded-for
                      parameter_set: browser_fingerprint
                      next_action: retry
components:
  schemas:
    OrganizationId:
      type: string
      pattern: ^org_[0123456789abcdefghjkmnpqrstvwxyz]{26}$
      example: org_f6m39y94nh6fs513q03skj929c
    ApiKeyId:
      type: string
      pattern: ^key_[0123456789abcdefghjkmnpqrstvwxyz]{26}$
      example: key_6cw04zdmetw8t5rsdppadhper0
    IssuedApiKeyResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/IssuedApiKey'
          example:
            object: api_key
            id: key_6cw04zdmetw8t5rsdppadhper0
            type: publishable
            environment: live
            name: Acme Growth Workspace
            status: active
            allowed_origins:
              - https://app.acme.co/signup
            scopes:
              - '*'
            rate_limit: 1
            key_preview: FOIL_SAMPLE_KEY
            display_key: FOIL_SAMPLE_KEY
            revealed_key: FOIL_SAMPLE_KEY
            last_used_at: '2026-03-24T20:00:05.000Z'
            created_at: '2026-03-24T20:00:00.000Z'
            rotated_at: '2026-03-24T20:00:05.000Z'
            revoked_at: '2026-03-24T20:00:05.000Z'
            grace_expires_at: '2026-03-24T20:00:05.000Z'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          example:
            request_id: req_cf147349a4134208aebb8c70e25fb7e1
      example:
        data:
          object: api_key
          id: key_6cw04zdmetw8t5rsdppadhper0
          type: publishable
          environment: live
          name: Acme Growth Workspace
          status: active
          allowed_origins:
            - https://app.acme.co/signup
          scopes:
            - '*'
          rate_limit: 1
          key_preview: FOIL_SAMPLE_KEY
          display_key: FOIL_SAMPLE_KEY
          revealed_key: FOIL_SAMPLE_KEY
          last_used_at: '2026-03-24T20:00:05.000Z'
          created_at: '2026-03-24T20:00:00.000Z'
          rotated_at: '2026-03-24T20:00:05.000Z'
          revoked_at: '2026-03-24T20:00:05.000Z'
          grace_expires_at: '2026-03-24T20:00:05.000Z'
        meta:
          request_id: req_cf147349a4134208aebb8c70e25fb7e1
    ApiErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PublicError'
          example:
            code: request.validation_failed
            message: Observation payload failed validation.
            status: 1
            retryable: true
            request_id: req_cf147349a4134208aebb8c70e25fb7e1
            docs_url: https://app.acme.co/signup
            details:
              fields:
                - name: Acme Growth Workspace
                  issue: required
                  expected: string
                  received: any_of
              allowed_values:
                - verified
              header_name: x-forwarded-for
              parameter_set: browser_fingerprint
              next_action: retry
      example:
        error:
          code: request.validation_failed
          message: Observation payload failed validation.
          status: 1
          retryable: true
          request_id: req_cf147349a4134208aebb8c70e25fb7e1
          docs_url: https://app.acme.co/signup
          details:
            fields:
              - name: Acme Growth Workspace
                issue: required
                expected: string
                received: any_of
            allowed_values:
              - verified
            header_name: x-forwarded-for
            parameter_set: browser_fingerprint
            next_action: retry
    IssuedApiKey:
      type: object
      additionalProperties: false
      required:
        - object
        - id
        - type
        - environment
        - name
        - status
        - allowed_origins
        - scopes
        - rate_limit
        - key_preview
        - last_used_at
        - created_at
        - rotated_at
        - revoked_at
        - grace_expires_at
        - revealed_key
      properties:
        object:
          const: api_key
          example: api_key
        id:
          $ref: '#/components/schemas/ApiKeyId'
          example: key_6cw04zdmetw8t5rsdppadhper0
        type:
          type: string
          enum:
            - publishable
            - secret
          example: publishable
        environment:
          $ref: '#/components/schemas/ApiKeyEnvironment'
          example: live
        name:
          type: string
          example: Acme Growth Workspace
        status:
          $ref: '#/components/schemas/ApiKeyStatus'
          example: active
        allowed_origins:
          anyOf:
            - type: array
              items:
                type: string
                format: uri
                example: https://app.acme.co/signup
              example:
                - https://app.acme.co/signup
            - type: 'null'
              example: null
          example:
            - https://app.acme.co/signup
        scopes:
          anyOf:
            - type: array
              items:
                type: string
                example: '*'
                enum:
                  - '*'
                  - sessions:list
                  - sessions:read
                  - sessions:update
                  - fingerprints:list
                  - fingerprints:read
                  - organizations:create
                  - organizations:read
                  - organizations:update
                  - api_keys:read
                  - api_keys:manage
                  - gate:agent_tokens:verify
                  - gate:agent_tokens:revoke
                  - gate:login_sessions:consume
                  - gate:services:read
                  - gate:services:manage
                  - webhooks:read
                  - webhooks:manage
              example:
                - '*'
            - type: 'null'
              example: null
          example:
            - '*'
        rate_limit:
          anyOf:
            - type: integer
              minimum: 1
              example: 1
            - type: 'null'
              example: null
          example: 1
        key_preview:
          type: string
          example: FOIL_SAMPLE_KEY
        display_key:
          type: string
          example: FOIL_SAMPLE_KEY
        revealed_key:
          type: string
          example: FOIL_SAMPLE_KEY
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:05.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-03-24T20:00:00.000Z'
        rotated_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:05.000Z'
        revoked_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:05.000Z'
        grace_expires_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:05.000Z'
      example:
        object: api_key
        id: key_6cw04zdmetw8t5rsdppadhper0
        type: publishable
        environment: live
        name: Acme Growth Workspace
        status: active
        allowed_origins:
          - https://app.acme.co/signup
        scopes:
          - '*'
        rate_limit: 1
        key_preview: FOIL_SAMPLE_KEY
        display_key: FOIL_SAMPLE_KEY
        revealed_key: FOIL_SAMPLE_KEY
        last_used_at: '2026-03-24T20:00:05.000Z'
        created_at: '2026-03-24T20:00:00.000Z'
        rotated_at: '2026-03-24T20:00:05.000Z'
        revoked_at: '2026-03-24T20:00:05.000Z'
        grace_expires_at: '2026-03-24T20:00:05.000Z'
    ResponseMeta:
      type: object
      additionalProperties: false
      required:
        - request_id
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
          example: req_cf147349a4134208aebb8c70e25fb7e1
      example:
        request_id: req_cf147349a4134208aebb8c70e25fb7e1
    PublicError:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - status
        - retryable
        - request_id
      properties:
        code:
          type: string
          x-foil-known-values-ref: '#/components/schemas/KnownPublicErrorCode'
          example: request.validation_failed
        message:
          type: string
          example: Observation payload failed validation.
        status:
          type: integer
          example: 1
        retryable:
          type: boolean
          example: true
        request_id:
          $ref: '#/components/schemas/RequestId'
          example: req_cf147349a4134208aebb8c70e25fb7e1
        docs_url:
          type: string
          format: uri
          example: https://app.acme.co/signup
        details:
          $ref: '#/components/schemas/ApiErrorDetails'
          example:
            fields:
              - name: Acme Growth Workspace
                issue: required
                expected: string
                received: any_of
            allowed_values:
              - verified
            header_name: x-forwarded-for
            parameter_set: browser_fingerprint
            next_action: retry
      example:
        code: request.validation_failed
        message: Observation payload failed validation.
        status: 1
        retryable: true
        request_id: req_cf147349a4134208aebb8c70e25fb7e1
        docs_url: https://app.acme.co/signup
        details:
          fields:
            - name: Acme Growth Workspace
              issue: required
              expected: string
              received: any_of
          allowed_values:
            - verified
          header_name: x-forwarded-for
          parameter_set: browser_fingerprint
          next_action: retry
    ApiKeyEnvironment:
      type: string
      enum:
        - live
        - test
      example: live
    ApiKeyStatus:
      type: string
      enum:
        - active
        - rotating
        - revoked
      example: active
    RequestId:
      type: string
      pattern: ^req_[0-9a-f]{32}$
      example: req_cf147349a4134208aebb8c70e25fb7e1
    ApiErrorDetails:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ApiFieldIssue'
            example:
              name: Acme Growth Workspace
              issue: required
              expected: string
              received: any_of
          example:
            - name: Acme Growth Workspace
              issue: required
              expected: string
              received: any_of
        allowed_values:
          type: array
          items:
            type: string
            example: verified
          example:
            - verified
        header_name:
          type: string
          example: x-forwarded-for
        parameter_set:
          type: string
          example: browser_fingerprint
        next_action:
          type: string
          enum:
            - retry
            - new_session
            - reload_bundle
            - contact_support
          example: retry
      additionalProperties: true
      example:
        fields:
          - name: Acme Growth Workspace
            issue: required
            expected: string
            received: any_of
        allowed_values:
          - verified
        header_name: x-forwarded-for
        parameter_set: browser_fingerprint
        next_action: retry
    ApiFieldIssue:
      type: object
      additionalProperties: false
      required:
        - name
        - issue
      properties:
        name:
          type: string
          example: Acme Growth Workspace
        issue:
          type: string
          example: required
        expected:
          type: string
          example: string
        received:
          anyOf:
            - type: string
              example: '0'
            - type: number
              example: 1.5
            - type: boolean
              example: true
            - type: 'null'
              example: null
          example: any_of
      example:
        name: Acme Growth Workspace
        issue: required
        expected: string
        received: any_of

````