openapi: 3.0.3
info:
  title: idp-server コントロールプレーン 身元確認設定管理 API
  description: 身元確認設定の管理API仕様書
  version: 1.0.0
  contact:
    name: idp-server OSS
servers:
- url: http://localhost:8080
tags:
- name: organization-identity-verification
  description: 組織レベル身元確認設定管理
paths:
  /v1/management/organizations/{organization-id}/tenants/{tenant-id}/identity-verification-configurations:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    - $ref: '#/components/parameters/TenantId'
    post:
      summary: 組織内身元確認設定作成
      description: 指定した組織・テナント内に新しい身元確認設定を作成します
      tags:
      - organization-identity-verification
      parameters:
      - $ref: '#/components/parameters/DryRun'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationIdentityVerificationConfigCreateRequest'
      responses:
        '201':
          description: 身元確認設定作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIdentityVerificationConfigResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: 身元確認設定が既に存在します
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: 組織内身元確認設定一覧取得
      description: 指定した組織・テナント内の身元確認設定一覧を取得します
      tags:
      - organization-identity-verification
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - name: id
        in: query
        required: false
        schema:
          type: string
        description: 設定IDでフィルタリング
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: 検証タイプでフィルタリング
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 作成日時の開始（ISO 8601形式）
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 作成日時の終了（ISO 8601形式）
      - $ref: '#/components/parameters/DryRun'
      responses:
        '200':
          description: 身元確認設定一覧
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationIdentityVerificationConfig'
                  total_count:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 組織またはテナントが見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/management/organizations/{organization-id}/tenants/{tenant-id}/identity-verification-configurations/{config-id}:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/IdentityVerificationConfigId'
    get:
      summary: 組織内身元確認設定詳細取得
      description: 指定した組織・テナント内の特定の身元確認設定の詳細を取得します
      tags:
      - organization-identity-verification
      responses:
        '200':
          description: 身元確認設定詳細
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIdentityVerificationConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 組織、テナント、または身元確認設定が見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: 組織内身元確認設定更新
      description: 指定した組織・テナント内の特定の身元確認設定を更新します
      tags:
      - organization-identity-verification
      parameters:
      - $ref: '#/components/parameters/DryRun'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationIdentityVerificationConfigUpdateRequest'
      responses:
        '200':
          description: 身元確認設定更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIdentityVerificationConfigResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 組織、テナント、または身元確認設定が見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: 組織内身元確認設定削除
      description: 指定した組織・テナント内の特定の身元確認設定を削除します
      tags:
      - organization-identity-verification
      parameters:
      - $ref: '#/components/parameters/DryRun'
      responses:
        '204':
          description: 身元確認設定削除成功
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 組織、テナント、または身元確認設定が見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    TenantId:
      name: tenant-id
      in: path
      required: true
      schema:
        type: string
      description: テナントの識別子
    OrganizationId:
      name: organization-id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: 組織の識別子
    IdentityVerificationConfigId:
      name: config-id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: 身元確認設定の識別子
    DryRun:
      name: dry_run
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: trueの場合、リクエストの検証のみで実行はされません
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20
      description: 返すアイテムの最大数
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: アイテムを返す開始インデックス
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_description:
          type: string
          description: Human-readable error description
        error_messages:
          type: array
          items:
            type: string
            description: Human-readable validation error message.
        error_details:
          type: object
          additionalProperties: true
          description: Additional error details
    MappingRule:
      type: object
      description: Mapping rule configuration based on MappingRule Java class
      properties:
        from:
          type: string
          description: Source field path for mapping
        static_value:
          description: Static value to use instead of mapping from source
        to:
          type: string
          description: Target field path for mapping
        convert_type:
          type: string
          description: Data conversion type
        functions:
          type: array
          description: List of transformation functions
          items:
            type: object
            additionalProperties: true
      additionalProperties: false
    OrganizationIdentityVerificationConfig:
      type: object
      required:
      - id
      - type
      - enabled
      properties:
        id:
          type: string
          format: uuid
          description: Identity verification configuration ID
          example: 473b4179-6bed-4465-b64e-ab8969a3e8ae
        type:
          type: string
          description: Identity verification configuration type
          example: document_verification
        enabled:
          type: boolean
          description: Whether the identity verification configuration is enabled
          default: true
        attributes:
          type: object
          description: 設定属性
          additionalProperties: true
          example: {}
        common:
          $ref: '#/components/schemas/IdentityVerificationCommonConfiguration'
        processes:
          type: object
          description: Process configurations by name
          additionalProperties:
            $ref: '#/components/schemas/IdentityVerificationProcessConfiguration'
        registration:
          $ref: '#/components/schemas/IdentityVerificationRegistrationConfig'
        result:
          $ref: '#/components/schemas/IdentityVerificationResultConfig'
      additionalProperties: false
    OrganizationIdentityVerificationConfigCreateRequest:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          format: uuid
          description: Identity verification configuration ID (must be UUID)
          example: 473b4179-6bed-4465-b64e-ab8969a3e8ae
        type:
          type: string
          description: Identity verification configuration type
          example: document_verification
        enabled:
          type: boolean
          description: Whether the identity verification configuration is enabled
          default: true
        attributes:
          type: object
          description: 設定属性
          additionalProperties: true
          example: {}
        common:
          $ref: '#/components/schemas/IdentityVerificationCommonConfiguration'
        processes:
          type: object
          description: Process configurations by name
          additionalProperties:
            $ref: '#/components/schemas/IdentityVerificationProcessConfiguration'
        registration:
          $ref: '#/components/schemas/IdentityVerificationRegistrationConfig'
        result:
          $ref: '#/components/schemas/IdentityVerificationResultConfig'
      additionalProperties: false
    OrganizationIdentityVerificationConfigUpdateRequest:
      type: object
      properties:
        type:
          type: string
          description: Identity verification configuration type
          example: enhanced_document_verification
        enabled:
          type: boolean
          description: Whether the identity verification configuration is enabled
        attributes:
          type: object
          description: 設定属性
          additionalProperties: true
          example: {}
        common:
          $ref: '#/components/schemas/IdentityVerificationCommonConfiguration'
        processes:
          type: object
          description: Process configurations by name
          additionalProperties:
            $ref: '#/components/schemas/IdentityVerificationProcessConfiguration'
        registration:
          $ref: '#/components/schemas/IdentityVerificationRegistrationConfig'
        result:
          $ref: '#/components/schemas/IdentityVerificationResultConfig'
      additionalProperties: false
    OrganizationIdentityVerificationConfigResponse:
      type: object
      required:
      - dry_run
      - result
      properties:
        dry_run:
          type: boolean
          description: Whether this was a dry run request
          example: false
        result:
          $ref: '#/components/schemas/OrganizationIdentityVerificationConfig'
      additionalProperties: false
    IdentityVerificationCommonConfiguration:
      type: object
      properties:
        callback_application_id_param:
          type: string
          description: Callback application ID parameter
        auth_type:
          type: string
          description: Authentication type
        oauth_authorization:
          $ref: '#/components/schemas/OAuthAuthorizationConfiguration'
        hmac_authentication:
          $ref: '#/components/schemas/HmacAuthenticationConfig'
      additionalProperties: false
    IdentityVerificationProcessConfiguration:
      type: object
      properties:
        caller:
          type: string
          enum: [end_user, external_service]
          description: |
            process を呼べる入口。`end_user` はエンドユーザー向けの API（`/v1/me/...`）だけ、`external_service` はコールバック API（`/internal/...`）だけ。
            省略すると、`request.basic_auth` があればコールバックだけ、なければ両方から呼べる。呼べない入口からは、登録されていない process と同じ 404 になる。
            `end_user` に `request.basic_auth`（`username` と `password` の両方）を書くと 400。
        request:
          $ref: '#/components/schemas/IdentityVerificationRequestConfig'
        pre_hook:
          $ref: '#/components/schemas/IdentityVerificationPreHookConfig'
        execution:
          $ref: '#/components/schemas/IdentityVerificationExecutionConfig'
        post_hook:
          $ref: '#/components/schemas/IdentityVerificationPostHookConfig'
        transition:
          $ref: '#/components/schemas/IdentityVerificationTransitionConfig'
        store:
          $ref: '#/components/schemas/IdentityVerificationStoreConfig'
        response:
          $ref: '#/components/schemas/IdentityVerificationResponseConfig'
      additionalProperties: false
    IdentityVerificationRequestConfig:
      type: object
      properties:
        basic_auth:
          $ref: '#/components/schemas/IdentityVerificationBasicAuthConfig'
        schema:
          type: object
          additionalProperties: true
      additionalProperties: false
    IdentityVerificationBasicAuthConfig:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
      additionalProperties: false
    IdentityVerificationPreHookConfig:
      type: object
      additionalProperties: true
    IdentityVerificationExecutionConfig:
      type: object
      properties:
        http_request:
          $ref: '#/components/schemas/IdentityVerificationHttpRequestConfig'
        mock:
          $ref: '#/components/schemas/IdentityVerificationMockConfig'
      additionalProperties: false
    IdentityVerificationHttpRequestConfig:
      type: object
      properties:
        url:
          type: string
          format: uri
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
        headers:
          type: object
          additionalProperties:
            type: string
        oauth_authorization:
          $ref: '#/components/schemas/OAuthAuthorizationConfiguration'
        hmac_authentication:
          $ref: '#/components/schemas/HmacAuthenticationConfig'
      additionalProperties: false
    IdentityVerificationMockConfig:
      type: object
      properties:
        enabled:
          type: boolean
        response:
          type: object
          additionalProperties: true
      additionalProperties: false
    IdentityVerificationPostHookConfig:
      type: object
      additionalProperties: true
    IdentityVerificationTransitionConfig:
      type: object
      properties:
        approved:
          $ref: '#/components/schemas/IdentityVerificationConditionConfig'
        rejected:
          $ref: '#/components/schemas/IdentityVerificationConditionConfig'
        canceled:
          $ref: '#/components/schemas/IdentityVerificationConditionConfig'
      additionalProperties: false
    IdentityVerificationConditionConfig:
      type: object
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/IdentityVerificationCondition'
      additionalProperties: false
    IdentityVerificationCondition:
      type: object
      properties:
        path:
          type: string
          description: JSONPath expression
        operator:
          type: string
          enum:
          - eq
          - ne
          - gt
          - lt
          - gte
          - lte
          - contains
          - exists
        value:
          description: Expected value for comparison
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - array
          - object
      additionalProperties: false
    IdentityVerificationStoreConfig:
      type: object
      properties:
        enabled:
          type: boolean
        mapping_rules:
          type: array
          items:
            $ref: '#/components/schemas/MappingRule'
      additionalProperties: false
    IdentityVerificationResponseConfig:
      type: object
      properties:
        template:
          type: string
        content_type:
          type: string
      additionalProperties: false
    IdentityVerificationRegistrationConfig:
      type: object
      properties:
        enabled:
          type: boolean
        auto_registration:
          type: boolean
        required_attributes:
          type: array
          items:
            type: string
      additionalProperties: false
    IdentityVerificationResultConfig:
      type: object
      properties:
        verified_claims_mapping_rules:
          type: array
          items:
            $ref: '#/components/schemas/MappingRule'
        source_details_mapping_rules:
          type: array
          items:
            $ref: '#/components/schemas/MappingRule'
      additionalProperties: false
    OAuthAuthorizationConfiguration:
      type: object
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        token_endpoint:
          type: string
          format: uri
        scope:
          type: string
      additionalProperties: false
    HmacAuthenticationConfig:
      type: object
      properties:
        secret_key:
          type: string
        algorithm:
          type: string
          enum:
          - HmacSHA256
          - HmacSHA512
        header_name:
          type: string
      additionalProperties: false
  responses:
    BadRequest:
      description: Bad Request - Invalid input parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error type
                example: invalid_request
              error_description:
                type: string
                description: Human-readable description of the error
                example: The request is missing required parameters
              details:
                type: object
                description: Additional error details
                additionalProperties: true
            required:
            - error
            - error_description
            additionalProperties: false
    Unauthorized:
      description: Unauthorized - Authentication required or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error type
                example: unauthorized
              error_description:
                type: string
                description: Human-readable description of the error
                example: Authentication required
            required:
            - error
            - error_description
            additionalProperties: false
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error type
                example: access_denied
              error_description:
                type: string
                description: Human-readable description of the error
                example: Insufficient permissions to access this resource
            required:
            - error
            - error_description
            additionalProperties: false