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

# 인가 엔드포인트

> PKCE를 사용한 OAuth 2.1 인가 코드 플로우를 시작합니다.

로그인 및 동의 폼을 렌더링합니다. 사용자가 인증하고 스토어를 선택하면
브라우저가 `redirect_uri`로 인가 `code`와 `state`를 포함하여 리다이렉트됩니다.




## OpenAPI

````yaml openapi.ko.yaml get /oauth/authorize
openapi: 3.1.0
info:
  title: Headless Commerce API
  description: >
    Headless Commerce as a Service — REST API 명세서.


    ## 인증

    모든 요청에 API 키를 Bearer 토큰으로 전달하세요.

    - **Secret Key** (`sk_live_*`, `sk_test_*`): 서버 사이드. Admin + Storefront API
    전체 접근 가능.

    - **Publishable Key** (`pk_live_*`, `pk_test_*`): 클라이언트 사이드. Storefront API만
    접근 가능.


    ## 고객 인증 (Storefront)

    고객 식별이 필요한 Storefront 엔드포인트 (/storefront/customers/*, /storefront/orders/*)는

    `X-Customer-Token` 헤더가 필요합니다.

    1. 백엔드에서 `sk_*` 키로 `POST /admin/customers/{id}/token`을 호출하여 토큰 발급

    2. 프론트엔드에서 `pk_*` 키 + `X-Customer-Token` 헤더와 함께 요청 전송


    ## 페이지네이션

    커서 기반 페이지네이션을 사용합니다.

    - `limit`: 페이지 크기 (기본 20, 최대 100)

    - `starting_after`: 이 ID 이후의 결과 반환

    - 응답에 `has_more`와 `next_cursor` 포함


    ## 금액

    모든 금액은 최소 통화 단위의 정수입니다 (KRW=원, USD=센트).


    ## 속도 제한

    모든 응답에 다음 헤더가 포함됩니다:

    - `X-RateLimit-Limit`: 분당 최대 요청 수 (플랜별: Free 100, Starter 500, Pro 2000,
    Enterprise 10000)

    - `X-RateLimit-Remaining`: 현재 윈도우의 남은 요청 수

    - 초과 시 `429 Too Many Requests` 반환


    ## 멱등성

    결제/주문 관련 POST 요청에 `Idempotency-Key` 헤더를 포함하면 동일한 키의 중복 요청에 대해 원래 응답을 반환합니다.

    권장 대상: checkout, refund, payment 생성
  version: 1.0.0
  contact:
    name: Headless Commerce Support
    url: https://headlesscommerce.io
servers:
  - url: https://api.headlesscommerce.io/v1
    description: 프로덕션
  - url: https://api.headlesscommerce.io/v1
    description: 테스트 (동일 URL, 테스트 API 키)
security:
  - BearerAuth: []
tags:
  - name: Storefront - Products
    description: 구매자를 위한 상품 조회
  - name: Storefront - Cart
    description: 장바구니 관리 및 결제
  - name: Storefront - Orders
    description: 주문 조회 (본인 주문)
  - name: Storefront - Customers
    description: 고객 프로필 (본인 프로필)
  - name: Storefront - Shipping
    description: 배송 방법 조회
  - name: Admin - Products
    description: 상품 관리
  - name: Admin - Variants
    description: 변형(Variant) 관리
  - name: Admin - Categories
    description: 카테고리 관리
  - name: Admin - Collections
    description: 컬렉션 관리
  - name: Admin - Inventory
    description: 재고 관리
  - name: Admin - Orders
    description: 주문 관리
  - name: Admin - Fulfillments
    description: 출고 관리
  - name: Admin - Customers
    description: 고객 관리
  - name: Admin - Discounts
    description: 할인 관리
  - name: Admin - Shipping Methods
    description: 배송 방법 관리
  - name: Admin - Webhooks
    description: 웹훅 관리
  - name: Admin - Store
    description: 스토어 설정
  - name: Admin - Settings
    description: API 키, 조직 및 팀 관리
  - name: Admin - Returns
    description: 반품 관리
  - name: Admin - Regions
    description: 리전, 다국어 및 환율 관리
  - name: Admin - Dashboard
    description: 대시보드 통계
  - name: Admin - Logs
    description: API 로그 조회
  - name: Admin - Uploads
    description: 파일 업로드
  - name: Storefront - Returns
    description: 고객 반품 요청 및 조회
  - name: Storefront - Customer Auth
    description: 고객 회원가입 및 로그인
  - name: Storefront - Payments
    description: 결제 확인
  - name: OAuth
    description: OAuth 2.1 인가 코드 플로우 (PKCE 지원)
  - name: Auth
    description: 대시보드 사용자 비밀번호 재설정
  - name: Admin - CSV
    description: 대량 CSV 가져오기 및 내보내기
paths:
  /oauth/authorize:
    get:
      tags:
        - OAuth
      summary: 인가 엔드포인트
      description: |
        PKCE를 사용한 OAuth 2.1 인가 코드 플로우를 시작합니다.

        로그인 및 동의 폼을 렌더링합니다. 사용자가 인증하고 스토어를 선택하면
        브라우저가 `redirect_uri`로 인가 `code`와 `state`를 포함하여 리다이렉트됩니다.
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: '`/oauth/register`에서 발급받은 OAuth 클라이언트 ID'
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: 등록된 리다이렉트 URI
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - code
          description: '`code`여야 합니다'
        - name: scope
          in: query
          schema:
            type: string
            default: admin
          description: '공백으로 구분된 스코프 (예: `products:read orders:write`)'
        - name: state
          in: query
          schema:
            type: string
          description: 리다이렉트에서 반환되는 CSRF 방지 토큰
        - name: code_challenge
          in: query
          required: true
          schema:
            type: string
          description: PKCE 코드 챌린지 (SHA-256 해시의 Base64-URL)
        - name: code_challenge_method
          in: query
          schema:
            type: string
            enum:
              - S256
            default: S256
      responses:
        '200':
          description: HTML 로그인/동의 폼
          content:
            text/html:
              schema:
                type: string
        '400':
          description: 잘못된 요청 파라미터
          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'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.