openapi: 3.0.3
info:
  title: Private API session authority
  version: 1.0.0
  description: Explicitly enrolled server protocol for the retained auth adaptor and credential worker. Excluded from public ingress.
x-activation: explicit-enrolment
components:
  securitySchemes:
    LegacyAuthAdaptor:
      type: http
      scheme: bearer
      description: Dedicated scoped server credential; distinct from browsers, CLI, bridge v1 and policy lookup.
    CredentialWorker:
      type: http
      scheme: bearer
      description: Separate credential with session-fence read permission only.
    AcceptedEvidenceReader:
      type: http
      scheme: bearer
      description: Separate scoped credential for accepted identity evidence required by enrolled account work.
    BindingWriter:
      type: http
      scheme: bearer
      description: Separate enrolled compatibility writer credential for signed provider ownership evidence.
    BindingReader:
      type: http
      scheme: bearer
      description: Separate scoped credential for current provider-binding reads required by policy and credential work.
paths:
  /internal/auth/v1/provider-bindings/lookup:
    post:
      operationId: lookupCurrentProviderIdentity
      security:
        - BindingReader: []
      description: Read the owner's exact provider/instance/external-ID association within an enrolled scope. A different Party is forbidden; retained retired state is returned explicitly and grants no access. This operation changes no identity record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'provider_binding.schemas.yaml#/schemas/ProviderIdentityLookup'
      responses:
        '200':
          description: Current complete canonical binding for the exact requested Party and provider identity; no-store.
          content:
            application/json:
              schema:
                $ref: 'provider_binding.schemas.yaml#/schemas/ProviderBinding'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '404':
          description: No retained association exists for this exact provider identity.
          content:
            application/json:
              schema:
                $ref: 'common.schemas.yaml#/schemas/Error'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/provider-bindings/record:
    post:
      operationId: recordQualifiedProviderBinding
      security:
        - BindingWriter: []
      description: Relay immutable signed ownership evidence to Party Governance. The owner verifies its enrolled proof source and current Party identity before committing one canonical binding.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'provider_binding.schemas.yaml#/schemas/RecordProviderBinding'
      responses:
        '200':
          description: Committed established canonical binding; exact command replay returns the original outcome. No-store.
          content:
            application/json:
              schema:
                $ref: 'provider_binding.schemas.yaml#/schemas/ProviderBinding'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '409':
          $ref: 'common.schemas.yaml#/responses/Conflict'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/provider-bindings/resolve:
    post:
      operationId: readCurrentProviderBinding
      security:
        - BindingReader: []
      description: Resolve a canonical binding through the owner's current scoped query. Verify that its Party, provider and instance match the caller's enrolled work; retired associations grant no access.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'provider_binding.schemas.yaml#/schemas/ProviderBindingLookup'
      responses:
        '200':
          description: Current complete canonical binding including retained retired state; no-store.
          content:
            application/json:
              schema:
                $ref: 'provider_binding.schemas.yaml#/schemas/ProviderBinding'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '404':
          description: The requested canonical binding does not exist.
          content:
            application/json:
              schema:
                $ref: 'common.schemas.yaml#/schemas/Error'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/sessions/validate:
    post:
      operationId: validateLegacySession
      security:
        - LegacyAuthAdaptor: []
      description: Authorise the enrolled operation against current session, Party, AUP and relevant readiness. See the fixed operation/gate table in README.md.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'session.schemas.yaml#/schemas/LegacySessionRequest'
      responses:
        '200':
          description: Current allowed operation and correlated non-bearer fence; no-store. This is no reusable access grant.
          content:
            application/json:
              schema:
                $ref: 'session.schemas.yaml#/schemas/LegacySessionAllowed'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '409':
          $ref: 'common.schemas.yaml#/responses/Conflict'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/sessions/revoke:
    post:
      operationId: revokeLegacySession
      security:
        - LegacyAuthAdaptor: []
      description: Shared legacy sign-out action. Fence the API session and persist cleanup even while external authorities are unavailable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'session.schemas.yaml#/schemas/RevokeRequest'
      responses:
        '204':
          description: Revoked or already absent/expired; clear browser cookie at the calling boundary.
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/session-fences/check:
    post:
      operationId: checkCredentialSessionFence
      security:
        - CredentialWorker: []
      description: Check exact session/Party/generation/expiry before credential effects and before exposing their result. No bearer-token minting or browser authentication.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'common.schemas.yaml#/schemas/SessionFence'
      responses:
        '200':
          description: Exact requested fence plus current true/false; false also covers absence, revocation and changed generation. No-store.
          content:
            application/json:
              schema:
                $ref: 'session.schemas.yaml#/schemas/FenceResult'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/auth/v1/evidence/resolve:
    post:
      operationId: resolveAcceptedAccountEvidence
      security:
        - AcceptedEvidenceReader: []
      description: Resolve immutable accepted evidence correlated to Party and generation for enrolled account work. Recheck current Party eligibility; this creates no session or browser grant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'evidence.schemas.yaml#/schemas/EvidenceLookup'
      responses:
        '200':
          description: Correlated accepted identity evidence with validation provenance; no-store. Restricted personal data, excluded from logs and public events.
          content:
            application/json:
              schema:
                $ref: 'evidence.schemas.yaml#/schemas/AcceptedEvidence'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '404':
          description: No retained evidence for the requested Party, generation and digest.
          content:
            application/json:
              schema:
                $ref: 'common.schemas.yaml#/schemas/Error'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'