openapi: 3.1.0
info:
  title: user-engine portal API
  version: 0.1.0
servers:
  - url: /api/v1
security:
  - verifiedOidc: []
paths:
  /me:
    get:
      operationId: currentUser
      responses:
        "200":
          description: Current user and linked identities
        "403":
          $ref: "#/components/responses/Denied"
  /registrations:
    post:
      operationId: startRegistration
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Registration started
        "403":
          $ref: "#/components/responses/Denied"
  /registrations/{registrationId}/complete:
    post:
      operationId: completeRegistration
      parameters:
        - name: registrationId
          in: path
          required: true
          schema: {type: string}
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Registration completed
        "400":
          description: Missing verified factors or invalid state
  /tenants/{tenant}/users:
    get:
      operationId: listTenantUsers
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - {name: offset, in: query, schema: {type: integer, minimum: 0}}
        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 100}}
      responses:
        "200": {description: Tenant-scoped memberships}
        "403": {$ref: "#/components/responses/Denied"}
  /tenants/{tenant}/users/{userId}:
    patch:
      operationId: updateTenantUserLifecycle
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - name: userId
          in: path
          required: true
          schema: {type: string}
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200": {description: Tenant account updated}
        "403": {$ref: "#/components/responses/Denied"}
components:
  securitySchemes:
    verifiedOidc:
      type: openIdConnect
      openIdConnectUrl: https://kc.coulomb.social/.well-known/openid-configuration
  parameters:
    Tenant:
      name: tenant
      in: path
      required: true
      schema: {type: string}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: {type: string, minLength: 16, maxLength: 200}
  responses:
    Denied:
      description: Caller is unauthenticated or unauthorized