openapi: 3.1.0
info:
  title: Onboarding Draft Resume Contract
  version: 1.0.0
  description: |
    Internal action contract for managed tenant onboarding draft landing, selection,
    canonical route loading, and lifecycle-safe resume semantics.
servers:
  - url: https://tenantatlas.internal
paths:
  /admin/onboarding:
    get:
      operationId: onboardingDraftLanding
      summary: Resolve onboarding landing state for the current workspace
      description: |
        Returns one of three outcomes for the current authorized workspace:
        empty start state, redirect to a single resumable draft, or a picker view
        when multiple resumable drafts exist.
      responses:
        '200':
          description: Landing state rendered directly
        '302':
          description: Redirect to canonical draft route when exactly one resumable draft exists
        '403':
          description: Returned when the actor is in scope but lacks onboarding capability
        '404':
          description: Returned when workspace context is missing or inaccessible
  /admin/onboarding/{onboardingDraft}:
    parameters:
      - name: onboardingDraft
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: showOnboardingDraft
      summary: Load one explicit onboarding draft
      description: |
        Loads the requested draft if it exists, belongs to the current workspace,
        is authorized for the actor, and is resumable or otherwise viewable.
        Resume stage must be derived from persisted confirmed data. Non-resumable
        drafts may render a non-editable summary surface instead of the active wizard.
      responses:
        '200':
          description: Draft wizard or non-resumable summary rendered
        '403':
          description: Actor is in scope but lacks capability to access the draft surface
        '404':
          description: Draft not found, outside workspace, or inaccessible
    patch:
      operationId: updateOnboardingDraft
      summary: Persist a confirmed onboarding draft transition
      description: |
        Persists a confirmed step boundary or explicit draft selection outcome.
        Unsaved transient edits are out of scope and are not persisted by this contract.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                current_step:
                  type: string
                state:
                  type: object
                  additionalProperties: true
                selected_provider_connection_id:
                  type:
                    - integer
                    - 'null'
                verification_operation_run_id:
                  type:
                    - integer
                    - 'null'
      responses:
        '200':
          description: Confirmed state persisted
        '403':
          description: Actor lacks capability for the attempted confirmed transition
        '404':
          description: Draft not found or inaccessible
    post:
      operationId: transitionOnboardingDraftLifecycle
      summary: Apply an explicit lifecycle transition such as cancel or complete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum:
                    - cancel
                    - complete
                reason:
                  type:
                    - string
                    - 'null'
      responses:
        '200':
          description: Lifecycle transition applied
        '403':
          description: Actor lacks permission for the transition
        '404':
          description: Draft not found or inaccessible