> ## 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.

# Authorization Endpoint

> Starts the OAuth 2.1 Authorization Code flow with PKCE.

Renders a login and consent form. After the user authenticates
and selects a store, the browser is redirected to `redirect_uri`
with an authorization `code` and `state`.




## OpenAPI

````yaml openapi.yaml get /oauth/authorize
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:
  /oauth/authorize:
    get:
      tags:
        - OAuth
      summary: Authorization Endpoint
      description: |
        Starts the OAuth 2.1 Authorization Code flow with PKCE.

        Renders a login and consent form. After the user authenticates
        and selects a store, the browser is redirected to `redirect_uri`
        with an authorization `code` and `state`.
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: OAuth client identifier from `/oauth/register`
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: Registered redirect URI
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - code
          description: Must be `code`
        - name: scope
          in: query
          schema:
            type: string
            default: admin
          description: Space-separated scopes (e.g. `products:read orders:write`)
        - name: state
          in: query
          schema:
            type: string
          description: Opaque CSRF token returned in the redirect
        - name: code_challenge
          in: query
          required: true
          schema:
            type: string
          description: PKCE code challenge (Base64-URL of SHA-256 hash)
        - name: code_challenge_method
          in: query
          schema:
            type: string
            enum:
              - S256
            default: S256
      responses:
        '200':
          description: HTML login/consent form
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
      security: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx'

````