xdata-kr Membership API

openapi: 3.2.0
info:
  title: XBOSS Membership API
  description: '통합 REST API 서버 (홈택스 등). Human API guide: https://developer.xdata.kr · OpenAPI Reference: /docs'
  version: 2.0.0
security:
- basicClientCredential: []
- mcpOAuth2: []
tags:
- name: Membership
paths:
  /v1/membership/me:
    get:
      tags:
      - Membership
      summary: 내 멤버십/정책 스냅샷 조회
      description: '현재 인증 주체의 멤버십/정책 스냅샷 조회.


        응답은 AuthPolicyService 평가 결과(PrincipalContext + quota/rate snapshot)를 그대로 노출한다.'
      operationId: get_membership_me_v1_v1_membership_me_get
      parameters:
      - name: env_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: Env Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: X-Env-Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      responses:
        '200':
          description: 현재 주체의 멤버십·정책 스냅샷.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipMeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MembershipRateLimitAfterModel:
      properties:
        window_seconds:
          type: integer
          title: Window Seconds
          description: 평가 윈도우 길이(초).
        limit:
          type: integer
          title: Limit
          description: 윈도우당 허용 횟수.
        used:
          type: integer
          title: Used
          description: 현 윈도우 누적 횟수.
        remaining:
          type: integer
          title: Remaining
          description: 남은 횟수.
        reset_at:
          type: string
          title: Reset At
          description: 윈도우가 초기화되는 시각(ISO 8601).
      type: object
      required:
      - window_seconds
      - limit
      - used
      - remaining
      - reset_at
      title: MembershipRateLimitAfterModel
      description: 이 요청을 센 뒤의 레이트리밋. `RateLimitSnapshot` 의 거울이다.
    MembershipQuotaAfterModel:
      properties:
        limit:
          type: integer
          title: Limit
          description: 그 주기에 허용된 사용 토큰 수.
        used:
          type: integer
          title: Used
          description: 그 주기에 누적된 사용 토큰 수.
        remaining:
          type: integer
          title: Remaining
          description: 남은 사용 토큰 수.
        reset_at:
          type: string
          title: Reset At
          description: 주기가 초기화되는 시각(ISO 8601, KST).
        period:
          type: string
          enum:
          - day
          - month
          title: Period
          description: 이 수치가 세는 주기.
      type: object
      required:
      - limit
      - used
      - remaining
      - reset_at
      - period
      title: MembershipQuotaAfterModel
      description: '이 요청을 센 뒤의 쿼터. `QuotaSnapshot.to_dict(include_key=False)` 의 거울이다.


        `key` 칸은 **일부러 없다**(모듈 머리말). 테스트 환경에서만 의미가 있어 상위 칸이 선택이다.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MembershipMeResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: 조회 성공 여부. 이 라우트는 성공 시 늘 true 다.
        policy_decision_id:
          type: string
          title: Policy Decision Id
          description: 이 조회를 평가한 정책 결정의 식별자. 문의 시 이 값을 전달한다.
        principal_kind:
          anyOf:
          - type: string
            enum:
            - client
            - console_user
            - admin_user
            - legacy_api_key
            - system
          - type: 'null'
          title: Principal Kind
          description: 인증 주체의 종류.
        organization_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Organization Id
          description: 소속 조직 식별자. 조직 밖 주체는 없다.
        organization_role:
          anyOf:
          - type: string
            enum:
            - OWNER
            - ADMIN
            - MEMBER
          - type: 'null'
          title: Organization Role
          description: 그 조직에서의 역할.
        membership_tier:
          anyOf:
          - type: string
            enum:
            - FREE
            - PAID
          - type: 'null'
          title: Membership Tier
          description: 멤버십 등급.
        plan_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Name
          description: '멤버십이 가리키는 요금제의 공개명(예: 라이트, 스탠다드, PRO). 멤버십이 없으면 없다. 주의: 가입 직후 데모 단계 계정도 공개명은 「라이트」 로 나온다 - 단계(데모 vs 정식)를 가르려면 이 이름이 아니라 membership_tier(FREE 또는 PAID)와 환경을 본다.'
        subscription_status:
          anyOf:
          - type: string
            enum:
            - ACTIVE
            - PAUSED
            - CANCELED
            - EXPIRED
          - type: 'null'
          title: Subscription Status
          description: 구독 상태.
        organization_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Status
          description: '그 조직의 상태(organizations.status): ACTIVE · SUSPENDED · CLOSED. 조직 밖 주체는 없다. 이 칸을 싣기 전의 서버는 보내지 않는다(없음은 정상으로 읽는다). 정지 조직 소유자도 결제 관리 화면은 열려 있어(membership_self_read) 이 칸으로 정지를 안다.'
        quota_after:
          anyOf:
          - $ref: '#/components/schemas/MembershipQuotaAfterModel'
          - type: 'null'
          description: 현재 사용 토큰 쿼터 스냅샷. 이 조회(GET /v1/membership/me, request_kind=membership_self_read)는 **쿼터를 쓰지 않는다** - 읽기 전용 스냅샷이라 이 값을 읽어도 한도가 줄지 않는다(auth_policy_quota.QUOTA_SNAPSHOT_REQUEST_KINDS). 한도가 없는 환경에서는 없다. (rate_limit_after 와 달리 쿼터는 이 조회로 차감되지 않는다 - 이 조회가 쓰는 것은 프로세스 레이트리밋 토큰 1개뿐이다.)
        quota_month_after:
          anyOf:
          - $ref: '#/components/schemas/MembershipQuotaAfterModel'
          - type: 'null'
          description: 이번 주기(정식 환경은 결제 주기)의 월 사용량. period 는 month 다. 그 환경의 요금제가 월 한도를 두지 않으면 없다.
        demo_ends_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Demo Ends At
          description: 데모 환경이 닫히는 시각(ISO 8601, KST). 기한이 없거나 데모 승인 전이면 없다.
        rate_limit_after:
          $ref: '#/components/schemas/MembershipRateLimitAfterModel'
          description: 이 조회를 센 뒤의 레이트리밋.
      type: object
      required:
      - success
      - policy_decision_id
      - rate_limit_after
      title: MembershipMeResponse
      description: '`GET /v1/membership/me` 의 200 응답.


        **Optional 을 넉넉히 둔 이유**: 이 응답은 주체에 따라 칸이 비는 것이 정상이다. 조직에 속하지

        않은 주체는 `organization_id` 와 `organization_role` 이 없고, 운영 환경은 무제한이라

        `quota_after` 가 없다(`AuthPolicyDecision.quota_after` 가 `Optional` 인 그 까닭).

        `rate_limit_after` 만 선언이 필수다 - 결정 객체에서도 필수 칸이다.'
  securitySchemes:
    basicClientCredential:
      type: http
      scheme: basic
      description: 'Console-issued client credential. Send `Authorization: Basic base64(client_id:client_secret)`.'
    mcpOAuth2:
      type: oauth2
      description: For MCP clients. OAuth 2.0 authorization code flow with PKCE (S256) for public clients. The client_id is the HTTPS URL of an OAuth Client ID Metadata Document that XBOSS has allow-listed; dynamic client registration is not supported.
      flows:
        authorizationCode:
          authorizationUrl: https://api.xdata.kr/oauth/authorize
          tokenUrl: https://api.xdata.kr/oauth/token
          scopes: {}