> ## 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. # Token Endpoint > Exchanges an authorization code for tokens, or refreshes an existing token. **Authorization Code grant** (`grant_type=authorization_code`): - Requires `code`, `client_id`, `redirect_uri`, and `code_verifier` (PKCE). - Returns `access_token` (1 hour TTL) and `refresh_token` (30 day TTL). **Refresh Token grant** (`grant_type=refresh_token`): - Requires `refresh_token` and `client_id`. - Returns a new access token and rotated refresh token. ## OpenAPI ````yaml openapi.yaml post /oauth/token 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/token: post: tags: - OAuth summary: Token Endpoint description: > Exchanges an authorization code for tokens, or refreshes an existing token. **Authorization Code grant** (`grant_type=authorization_code`): - Requires `code`, `client_id`, `redirect_uri`, and `code_verifier` (PKCE). - Returns `access_token` (1 hour TTL) and `refresh_token` (30 day TTL). **Refresh Token grant** (`grant_type=refresh_token`): - Requires `refresh_token` and `client_id`. - Returns a new access token and rotated refresh token. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type - client_id properties: grant_type: type: string enum: - authorization_code - refresh_token code: type: string description: Authorization code (for `authorization_code` grant) client_id: type: string redirect_uri: type: string format: uri description: Must match the URI used in `/oauth/authorize` code_verifier: type: string description: PKCE code verifier (for `authorization_code` grant) refresh_token: type: string description: Refresh token (for `refresh_token` grant) responses: '200': description: Token response headers: Cache-Control: schema: type: string example: no-store content: application/json: schema: type: object properties: access_token: type: string token_type: type: string example: Bearer expires_in: type: integer example: 3600 refresh_token: type: string scope: type: string '400': description: Invalid grant or request content: application/json: schema: type: object properties: error: type: string enum: - invalid_request - invalid_client - invalid_grant - unsupported_grant_type error_description: type: string security: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx' ````