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

# Rotate API Key (Revoke Old + Issue New)



## OpenAPI

````yaml openapi.yaml post /admin/api-keys/{id}/rotate
openapi: 3.1.0
info:
  title: Headless Commerce API
  description: >
    Headless Commerce as a Service — REST API specification.


    ## Authentication

    Pass your API key as a Bearer token in every request.

    - **Secret Key** (`sk_live_*`, `sk_test_*`): Server-side. Full access to
    Admin + Storefront APIs.

    - **Publishable Key** (`pk_live_*`, `pk_test_*`): Client-side. Storefront
    API only.


    ## Customer Authentication (Storefront)

    Storefront endpoints that require customer identification
    (/storefront/customers/*, /storefront/orders/*)

    need the `X-Customer-Token` header.

    1. From your backend, call `POST /admin/customers/{id}/token` with an `sk_*`
    key to issue a token

    2. From the frontend, send requests with the `pk_*` key + `X-Customer-Token`
    header


    ## Pagination

    Uses cursor-based pagination.

    - `limit`: Page size (default 20, max 100)

    - `starting_after`: Return results after this ID

    - Response includes `has_more` and `next_cursor`


    ## Money

    All amounts are integers in the smallest currency unit (KRW=won, USD=cents).


    ## Rate Limiting

    All responses include the following headers:

    - `X-RateLimit-Limit`: Max requests per minute (by plan: Free 100, Starter
    500, Pro 2000, Enterprise 10000)

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - Returns `429 Too Many Requests` when exceeded


    ## Idempotency

    Include an `Idempotency-Key` header with payment/order-related POST requests
    to receive the original response for duplicate requests with the same key.

    Recommended for: checkout, refund, and payment creation
  version: 1.0.0
  contact:
    name: Headless Commerce Support
    url: https://headlesscommerce.io
servers:
  - url: https://api.headlesscommerce.io/v1
    description: Production
  - url: https://api.headlesscommerce.io/v1
    description: Test (same URL, test API key)
security:
  - BearerAuth: []
tags:
  - name: Storefront - Products
    description: Browse products for buyers
  - name: Storefront - Cart
    description: Cart management and checkout
  - name: Storefront - Orders
    description: View orders (own orders)
  - name: Storefront - Customers
    description: Customer profile (own profile)
  - name: Storefront - Shipping
    description: View shipping methods
  - name: Admin - Products
    description: Product management
  - name: Admin - Variants
    description: Variant management
  - name: Admin - Categories
    description: Category management
  - name: Admin - Collections
    description: Collection management
  - name: Admin - Inventory
    description: Inventory management
  - name: Admin - Orders
    description: Order management
  - name: Admin - Fulfillments
    description: Fulfillment management
  - name: Admin - Customers
    description: Customer management
  - name: Admin - Discounts
    description: Discount management
  - name: Admin - Shipping Methods
    description: Shipping method management
  - name: Admin - Webhooks
    description: Webhook management
  - name: Admin - Store
    description: Store settings
  - name: Admin - Settings
    description: API keys, organization, and team management
  - name: Admin - Returns
    description: Return management
  - name: Admin - Regions
    description: Region, i18n, and currency rate management
  - name: Admin - Dashboard
    description: Dashboard statistics
  - name: Admin - Logs
    description: API log viewing
  - name: Admin - Uploads
    description: File uploads
  - name: Storefront - Returns
    description: Customer return requests and viewing
  - name: Storefront - Customer Auth
    description: Customer registration and login
  - name: Storefront - Payments
    description: Payment confirmation
  - name: OAuth
    description: OAuth 2.1 Authorization Code flow with PKCE
  - name: Auth
    description: Dashboard user password reset
  - name: Admin - CSV
    description: Bulk CSV import and export
paths:
  /admin/api-keys/{id}/rotate:
    post:
      tags:
        - Admin - Settings
      summary: Rotate API Key (Revoke Old + Issue New)
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiKey'
                  - type: object
                    properties:
                      key:
                        type: string
                        description: New original key (returned once)
components:
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource ID
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - secret
            - publishable
        mode:
          type: string
          enum:
            - live
            - test
        key_hint:
          type: string
          description: Masked key (sk_live_...abc)
        is_active:
          type: boolean
        last_used_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx'

````