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

# 동적 클라이언트 등록

> [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)에 따라 OAuth 클라이언트를 동적으로 등록합니다.

`client_id`를 반환하며, 기밀 클라이언트의 경우 `client_secret`도 반환합니다.
`client_secret`은 등록 시 한 번만 반환되며 이후 조회할 수 없습니다.




## OpenAPI

````yaml openapi.ko.yaml post /oauth/register
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/register:
    post:
      tags:
        - OAuth
      summary: 동적 클라이언트 등록
      description: >
        [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)에 따라 OAuth
        클라이언트를 동적으로 등록합니다.


        `client_id`를 반환하며, 기밀 클라이언트의 경우 `client_secret`도 반환합니다.

        `client_secret`은 등록 시 한 번만 반환되며 이후 조회할 수 없습니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - client_name
                - redirect_uris
              properties:
                client_name:
                  type: string
                  description: 사람이 읽을 수 있는 클라이언트 이름
                redirect_uris:
                  type: array
                  items:
                    type: string
                    format: uri
                  minItems: 1
                  description: 등록할 리다이렉트 URI 목록
                grant_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - authorization_code
                      - refresh_token
                  default:
                    - authorization_code
                    - refresh_token
                token_endpoint_auth_method:
                  type: string
                  enum:
                    - none
                    - client_secret_post
                  default: none
                scope:
                  type: string
                  description: 기본 스코프
                logo_uri:
                  type: string
                  format: uri
                client_uri:
                  type: string
                  format: uri
      responses:
        '201':
          description: 클라이언트 등록 완료
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_secret:
                    type: string
                    nullable: true
                  client_name:
                    type: string
                  redirect_uris:
                    type: array
                    items:
                      type: string
                  grant_types:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_method:
                    type: string
                  scope:
                    type: string
                    nullable: true
                  logo_uri:
                    type: string
                    nullable: true
                  client_uri:
                    type: string
                    nullable: true
        '400':
          description: 잘못된 클라이언트 메타데이터
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_client_metadata
                  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.