AgenTrux Console Account API

openapi: 3.2.0
info:
  title: AgenTrux Console Account API
  version: 0.1.0
tags:
- name: console-account
paths:
  /console/me/auth-methods:
    get:
      tags:
      - console-account
      summary: Get My Auth Methods
      description: '自分が現在保有しているログイン手段を返す (名寄せ UI の元データ)。


        「ログイン方法」設定画面が、パスワード追加/削除・Google 連携解除の可否を判断するために使う。

        **最後の 1 手段は外させない**不変条件 (ログイン不能の防止) を UI 側で成立させるのが目的。


        Kratos の SPA 向け API は identity の credential 構成を返さない (意図的) ため、backend が

        admin API を代理で叩く。返すのは bool と provider 名のみで、秘密情報は一切含めない。


        Returns:

        {"password": bool, "oidc_providers": ["google"], "webauthn": bool,

        "total": int, "can_remove_one": bool}'
      operationId: get_my_auth_methods_console_me_auth_methods_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get My Auth Methods Console Me Auth Methods Get
  /console/me:
    get:
      tags:
      - console-account
      summary: Get Me Endpoint
      description: 'Phase 4.1a Codex impl review #2 反映: session 有効でも user が論理削除済の

        stale 状態を 500 ではなく 401 (`re_authenticate`) で返す。


        Codex impl review #6 反映: `email` / `display_name` は Phase 4.1a 範囲外。

        Kratos identity (traits.email / traits.display_name) からの取り込みは後続

        sub-step (4.1b/4.1c) で別経路 (Settings) として実装。 spec example の値あり

        前提は SSOT 側で `nullable` 明記済とする (注: endpoints_console.md §4-1-9

        `GET /console/settings/profile` がプロファイル取得の正本)。'
      operationId: get_me_endpoint_console_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Me Endpoint Console Me Get
  /console/me/profile:
    patch:
      tags:
      - console-account
      summary: Update My Profile
      description: 'Phase 4.9.5: 初回ログイン時の Profile Setup Wizard が呼ぶ。


        display_name (必須、 1-200 chars、 制御文字 / 改行 reject) + email (任意、 RFC 5322

        簡易 regex でフォーマット検証) を更新。 email を更新した場合は email_send_failed_at

        を NULL クリア (再設定完了とみなす)。'
      operationId: update_my_profile_console_me_profile_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_UpdateMyProfileBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Update My Profile Console Me Profile Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/me/login-history:
    get:
      tags:
      - console-account
      summary: List Login History
      description: 'ログイン履歴 (sessions table、 user_id 一致のみ、 4.11.1 標準準拠 list)。


        W.3.1 で plain list として実装、 Phase 4.9.2 で sessions.ip_address / hostname_resolved

        列を追加し、 Phase 4.11.1 横断 SSOT (list_ux_standard.md §3) に従って検索 / sort /

        filter / pagination 標準化した。


        SSOT:

        - docs/04_design/frontend/list_ux_standard.md §3 (query / response 形式)

        - docs/04_design/auth/provisioning_hardening.md §3-3 (IP / hostname 出し分け)

        - docs/04_design/auth/console_session.md (sessions lifecycle)


        Query (4.11.1 標準):

        - q: UA / hostname / IP (str) の部分一致

        - sort: created_at / last_seen_at (default created_at:desc)

        - filter[revoked]: true|false (revoked_at 状態)

        - filter[active]: true|false (now() 時点で有効な session)

        - cursor / limit: keyset (created_at, id)


        Response item:

        - ip_address (full INET、 caller=本人なので常に full、 他 user の参照は不可)

        - hostname (PTR resolved、 失敗時 NULL、 表示は参考情報)

        - 旧 ip_prefix も併存 (backward compat、 SPA 旧版表示用)'
      operationId: list_login_history_console_me_login_history_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Login History Console Me Login History Get
  /console/refresh-tokens:
    get:
      tags:
      - console-account
      summary: List Refresh Tokens Endpoint
      description: 'user_id に紐付く refresh_tokens の一覧 (caller=本人のみ).


        Query (4.11.1 標準):

        - q: client_id / token_family_id / id の部分一致

        - sort: created_at / last_used_at / expires_at (default created_at:desc)

        - filter[active]: true|false (revoked_at NULL かつ expires_at 未到来)

        - cursor / limit: keyset (created_at, id)


        token_hash 自体は API で返さない (秘匿)。 client_id / script_name は読みやすさのため JOIN。'
      operationId: list_refresh_tokens_endpoint_console_refresh_tokens_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Refresh Tokens Endpoint Console Refresh Tokens Get
  /console/accounts:
    get:
      tags:
      - console-account
      summary: List Accounts Endpoint
      operationId: list_accounts_endpoint_console_accounts_get
      parameters:
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: cursor (acc_<uuid> or org_<uuid>)
          title: After
        description: cursor (acc_<uuid> or org_<uuid>)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: 1..100
          default: 50
          title: Limit
        description: 1..100
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Accounts Endpoint Console Accounts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - console-account
      summary: Create Account Endpoint
      description: 'Phase BT.4.c: Group Account 作成。 Personal 作成は本 endpoint の責務外

        (sign-up / Kratos webhook 経路で自動生成)、 kind=''group'' のみ受け付ける。'
      operationId: create_account_endpoint_console_accounts_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_CreateGroupBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Account Endpoint Console Accounts Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}:
    get:
      tags:
      - console-account
      summary: Get Account Endpoint
      operationId: get_account_endpoint_console_accounts__acc_id__get
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Account Endpoint Console Accounts  Acc Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - console-account
      summary: Patch Account Endpoint
      description: 'spec §4-1-1: caller must be Owner (personal-self) or Owner/Admin (group).


        member role → 403 FORBIDDEN。 非所属 / 削除済 / kind mismatch → 404 (A4)。

        empty patch / display_name 1..200 外 → 422 INVALID。'
      operationId: patch_account_endpoint_console_accounts__acc_id__patch
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAccountBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Patch Account Endpoint Console Accounts  Acc Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/members:
    get:
      tags:
      - console-account
      summary: List Members Endpoint
      operationId: list_members_endpoint_console_accounts__acc_id__members_get
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: After
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Members Endpoint Console Accounts  Acc Id  Members Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/members/invite:
    post:
      tags:
      - console-account
      summary: Invite Member Endpoint
      description: 'Phase BT.4.e: email-based invite を新 command (invite_group_member) 経由で実行。


        SSOT:

        - docs/04_design/group_account.md §3-2 (Member 招待フロー)

        - docs/04_design/group_account.md §10 BT.4.e


        挙動 (caller は owner / admin role の Console session user 必須):

        1. caller_personal_account_id を session.user_id から resolve

        2. AccountSubscriptionGate (group_account.md §6-4) で ADMIN op を gate

        3. command に委譲 (advisory_xact_lock → cap pre-check → email lookup → 分岐)

        4. 既存 Starter+ user → auto-join (status=redeemed_existing)、

        既存 user なし → invitations row INSERT + raw invite_code 返却

        (status=pending_invite_code、 invite_code は新規発行時のみ平文 1 度限り)


        Removed in BT.4.k refactor:

        - W.3.3 の `member_account_id` 直接経路 (deprecated)

        - workspace_settings.domain_restriction enforcement (新 command に未実装、

        必要なら別 sub-step で再導入)'
      operationId: invite_member_endpoint_console_accounts__acc_id__members_invite_post
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteMemberBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Invite Member Endpoint Console Accounts  Acc Id  Members Invite Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/members/{mem_id}:
    delete:
      tags:
      - console-account
      summary: Remove Member Endpoint
      description: 'Phase BT.4.g — 最後の owner は 409 last_owner_cannot_leave、 owner 自身も他に

        owner がいる限り脱退可能。 自脱退 (member/admin/owner) は role check skip して許可。'
      operationId: remove_member_endpoint_console_accounts__acc_id__members__mem_id__delete
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      - name: mem_id
        in: path
        required: true
        schema:
          type: string
          title: Mem Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/members/{mem_id}/role:
    patch:
      tags:
      - console-account
      summary: Change Member Role Endpoint
      operationId: change_member_role_endpoint_console_accounts__acc_id__members__mem_id__role_patch
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      - name: mem_id
        in: path
        required: true
        schema:
          type: string
          title: Mem Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_ChangeRoleBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Change Member Role Endpoint Console Accounts  Acc Id  Members  Mem Id  Role Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/shared-aliases:
    post:
      tags:
      - console-account
      summary: Create Shared Alias Endpoint
      operationId: create_shared_alias_endpoint_console_accounts__acc_id__shared_aliases_post
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_CreateSharedAliasBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Shared Alias Endpoint Console Accounts  Acc Id  Shared Aliases Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/accounts/{acc_id}/topup-requests:
    post:
      tags:
      - console-account
      summary: Request Topup Endpoint
      operationId: request_topup_endpoint_console_accounts__acc_id__topup_requests_post
      parameters:
      - name: acc_id
        in: path
        required: true
        schema:
          type: string
          title: Acc Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_RequestTopUpBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Request Topup Endpoint Console Accounts  Acc Id  Topup Requests Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/group-invites/redeem:
    post:
      tags:
      - console-account
      summary: Redeem Group Invite Endpoint
      operationId: redeem_group_invite_endpoint_console_group_invites_redeem_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_RedeemBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Redeem Group Invite Endpoint Console Group Invites Redeem Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/me/authorized-clients:
    get:
      tags:
      - console-account
      summary: List Authorized Clients
      description: 自分の active refresh_token を持つ OAuth client を listing。
      operationId: list_authorized_clients_console_me_authorized_clients_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Authorized Clients Console Me Authorized Clients Get
  /console/me/authorized-clients/{client_id}:
    delete:
      tags:
      - console-account
      summary: Revoke Authorized Client
      description: '自分が持つ当該 client の全 refresh_token を family revoke。


        制約:

        - client_id は oauth_clients.client_id (TEXT)。 形式 validation は不要 (PK reference)。

        - 自分の active token が存在しない場合は 404 (他人の token 列挙を防止)。

        - revoke は state-conditional UPDATE (rowcount=0 = 既に revoke 済 / 不存在 = 404)。

        - aat_ は TTL (10 分) で自然失効、 SSE は次の token check で切れる。'
      operationId: revoke_authorized_client_console_me_authorized_clients__client_id__delete
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          title: Client Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/me/withdraw:
    post:
      tags:
      - console-account
      summary: Withdraw Me Endpoint
      description: 'Personal account の本人退会 (spec §1-1)。


        settlement flag ON なら settle_withdrawal 経由 (S6-b §3 bypass 不可)、OFF なら素の

        soft-delete — admin `/admin/debug/accounts/{id}/soft-delete` と完全同一分岐。

        退会後も console session は有効 (users.deleted_at は触らない、復元のため)。'
      operationId: withdraw_me_endpoint_console_me_withdraw_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawMeBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /console/me/withdrawal-status:
    get:
      tags:
      - console-account
      summary: Withdrawal Status Endpoint
      description: 退会済み状態の表示用 (spec §1-2)。deleting かつ猶予内のみ withdrawn=true。
      operationId: withdrawal_status_endpoint_console_me_withdrawal_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /console/me/restore:
    post:
      tags:
      - console-account
      summary: Restore Me Endpoint
      description: '猶予期間内の退会取消 (spec §1-3、FR-ACC-04)。


        復元されるのは account (active 化) と purge されていないデータのみ。Stripe subscription は

        退会時に解約済みのため有効 tier は free に落ちる (再購読は Console から)。restore 後に

        recompute_block_state で block flag を現 usage/quota で立て直す (共通 wiring)。'
      operationId: restore_me_endpoint_console_me_restore_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PatchAccountBody:
      properties:
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
      type: object
      title: PatchAccountBody
      description: 'spec §4-1-1 PATCH body. 現 phase は display_name のみ更新可能。


        `display_name=None` (もしくは body 全体省略) は empty patch → 422。'
    _ChangeRoleBody:
      properties:
        role:
          type: string
          enum:
          - owner
          - admin
          - member
          title: Role
      additionalProperties: false
      type: object
      required:
      - role
      title: _ChangeRoleBody
    _RedeemBody:
      properties:
        invite_code:
          type: string
          maxLength: 128
          minLength: 5
          title: Invite Code
      additionalProperties: false
      type: object
      required:
      - invite_code
      title: _RedeemBody
    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
    _UpdateMyProfileBody:
      properties:
        display_name:
          type: string
          maxLength: 200
          minLength: 1
          title: Display Name
        email:
          anyOf:
          - type: string
            maxLength: 320
            minLength: 3
          - type: 'null'
          title: Email
        acquisition_source:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Acquisition Source
      additionalProperties: false
      type: object
      required:
      - display_name
      title: _UpdateMyProfileBody
      description: 'Phase 4.9.5 + ユーザ要求 2026-05-23: display_name (必須) + email (任意).


        email は本 endpoint で更新可能 (Kratos verification は別 phase で配線)。

        email を渡した場合は users.email を上書き、 email_send_failed_at を NULL クリア。


        acquisition_source (任意): 初回 landing で frontend が捕捉した流入元 (referrer + utm_*)。

        set-once で users.acquisition_source に保存 (既に値があれば上書きしない)。'
    InviteMemberBody:
      properties:
        email:
          type: string
          maxLength: 320
          minLength: 1
          title: Email
        role:
          type: string
          enum:
          - admin
          - member
          title: Role
          default: member
      additionalProperties: false
      type: object
      required:
      - email
      title: InviteMemberBody
      description: 'Phase BT.4.e body (W.3.3 deprecated 経路は撤去済)。


        SSOT: docs/04_design/group_account.md §3-2 (Member 招待フロー)。

        `email` 必須、 既存 user lookup の結果で auto-join / invite_code 発行を分岐する。'
    _CreateSharedAliasBody:
      properties:
        display_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Display Name
      additionalProperties: false
      type: object
      required:
      - display_name
      title: _CreateSharedAliasBody
    WithdrawMeBody:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Reason
      additionalProperties: false
      type: object
      title: WithdrawMeBody
    _RequestTopUpBody:
      properties:
        request_type:
          type: string
          enum:
          - publish_1m
          - storage_10gb
          - egress_10gb
          title: Request Type
        quantity:
          type: integer
          minimum: 1.0
          title: Quantity
          default: 1
        reason:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Reason
      additionalProperties: false
      type: object
      required:
      - request_type
      title: _RequestTopUpBody
    _CreateGroupBody:
      properties:
        kind:
          type: string
          const: group
          title: Kind
        display_name:
          type: string
          maxLength: 200
          minLength: 1
          title: Display Name
        initial_shared_alias_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Initial Shared Alias Name
          default: shared
      additionalProperties: false
      type: object
      required:
      - kind
      - display_name
      title: _CreateGroupBody