openapi: 3.0.3
info:
  title: Kiban platform API
  version: "1.0.0"
  description: >
    The gateway-owned "platform" surface: every `/api/*` route mounted directly by
    `internal/gateway` itself (foundation_routes.go, platform_routes.go, admin_position_routes.go,
    admin_group_routes.go), as opposed to a module's own `/api/<moduleKey>/*` fragment.
    This is not a module: there is no module.manifest.json/
    authz.fragment.json for the platform; it is documented here because the module contract's
    binding rule ("the running service must enforce this contract at the HTTP boundary") applies
    equally to the platform's own consumer-facing surface, so a developer can use Kiban from
    docs alone.

    Every route here is a fixed reverse proxy (never the dynamic, opaque module-key proxy in
    proxy.go): the gateway rewrites the outbound path to an internal `/internal/...` route on
    one of the four foundation services (authz, org, registry) and, for the self-scoped reads,
    forces the outbound `kcSub` to the validated bearer's own subject (never a client-supplied
    value: see foundation_routes.go's own doc comment). All routes require a valid bearer
    (`RequireAuth`); routes under `.../admin/...` additionally require the superadmin guard
    (`RequireSuperadmin`): a fail-closed check: if authz itself is unreachable, the admin
    guard returns 503 `AUTHORIZATION_UNAVAILABLE`, never a silent allow.

    Validated the same way a module's own fragment is (the `internal/testopenapi` helper,
    `github.com/getkin/kin-openapi`): `internal/gateway/platform_openapi_live_test.go` drives real
    requests through a live kiban-test gateway and validates the recorded response against this
    fragment's declared schema: at least the happy path and one error per route, so this
    document is trustworthy, not aspirational.
servers:
  - url: /
security:
  - bearerAuth: []
paths:
  # ---- foundation_routes.go -------------------------------------------------------------------
  /api/auth/effective-access/can:
    post:
      operationId: effectiveAccessCan
      summary: Ask whether the caller (never an arbitrary actor) can do one thing
      description: >
        Bearer-gated fixed proxy to authz's own `/internal/authz/effective-access/can`
        (internal/authz/http.go). authz itself rejects a body naming a subject other than the
        bearer (400), and a `global`-scope request without `requiredPlatformRole` (400
        `VALIDATION_ERROR`), the gateway adds nothing beyond bearer validation at the edge.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EffectiveAccessRequest" }
      responses:
        "200":
          description: Decision (allow or deny, a denial is a normal 200, never an error status)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EffectiveAccessDecisionEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/auth/effective-access/batch-can:
    post:
      operationId: effectiveAccessBatchCan
      summary: Ask whether the caller can do several things in one round trip
      description: >
        Same subject and scope rules as `can`, bearer-gated fixed proxy to authz's own
        `/internal/authz/effective-access/batch-can`. At most 100 `items` per request (400
        `VALIDATION_ERROR` above); a request with denied items writes one audit event listing
        them (the first 50, with a `truncated` flag).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EffectiveAccessBatchRequest" }
      responses:
        "200":
          description: One decision per requested (object, relation) pair
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EffectiveAccessBatchEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/auth/effective-access/summary:
    get:
      operationId: effectiveAccessSummary
      summary: The caller's own display-composed access summary (a display aid, never an enforcement surface)
      description: >
        Self-scoped, internal-network-unauthenticated downstream (authz's own
        `/internal/authz/effective-access/summary`, kcSub as a plain query param), the gateway is
        the bearer-validating boundary and forces `kcSub` to the validated bearer's own subject,
        overwriting any client-supplied value. `objectAccess` is direct-tuples-only (never a
        userset-closure expansion);
        a position/group-held tier never appears here even when it is real and enforced elsewhere.
      parameters:
        - name: companyId
          in: query
          required: false
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: The caller's summary (apiVersion 1)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EffectiveAccessSummary" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/org/me/companies:
    get:
      operationId: orgMeCompanies
      summary: Companies where the caller has an active membership in an active company (the company switcher's source)
      description: Self-scoped fixed proxy to org's own `/internal/org/me/companies` (internal/org/http.go's handleMeCompanies), kcSub forced to the bearer's own subject.
      responses:
        "200":
          description: List of companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/OrgMeCompany" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/org/companies/{companyId}/members:
    get:
      operationId: orgCompanyMemberDirectory
      summary: The company's member directory (the least-disclosure share-with/assign-to picker source)
      description: >
        Bearer-gated fixed proxy to org's own `/internal/org/companies/{companyId}/members`,
        kcSub forced to the bearer's own subject. org's own handler enforces
        active-membership-or-superadmin (`requireMemberOrAdmin`), a non-member caller gets
        403, not a 404 (never leaks whether the company exists to an outsider vs. a non-member).
        A guest member is refused with 403 as well.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: q
          in: query
          schema: { type: string }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: Page of member-directory entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/MemberDirectoryEntry" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }

  /api/org/companies/{companyId}/positions:
    get:
      operationId: orgCompanyPositionDirectory
      summary: The company's positions, reduced to id, code and title (any active member, or a superadmin)
      description: >
        Bearer-gated fixed proxy to org's `/internal/org/companies/{companyId}/positions/directory`,
        kcSub forced to the bearer's own subject; the same guard as the member directory, so a
        guest member is refused with 403. The
        share-with or assign-to picker source beside it: no org unit, no holder. Grant to
        `position:<id>#holder` so access follows the chair.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: Page of position-directory entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/PositionDirectoryEntry" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }

  /api/org/companies/{companyId}/groups:
    get:
      operationId: orgCompanyGroupDirectory
      summary: The company's active groups, reduced to id, code and name (any active member, or a superadmin)
      description: >
        Bearer-gated fixed proxy to org's `/internal/org/companies/{companyId}/groups/directory`,
        same guard as the member directory, so a guest member is refused with 403; inactive
        groups are left out. Grant to
        `group:<id>#member` so access follows the membership.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: Page of group-directory entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/GroupDirectoryEntry" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }

  /api/org/companies/{companyId}/positions/{id}/holder:
    get:
      operationId: orgPositionHolder
      summary: The member holding a position on a date (any member of the company, or a superadmin)
      description: >
        Proxied to org's `/internal/org/positions/{id}/holder`. The caller must be an active
        member of the company (an app's service account counts once it is a member, a guest
        member does not) or the superadmin; a position of another company answers 404. Resolves approvers and
        owners "as of" a date.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: date
          in: query
          required: true
          schema: { type: string, format: date }
      responses:
        "200":
          description: The assignment in force on that date
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgAssignment" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: No holder on that date, or the position is not in this company
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/companies/{companyId}/groups/{id}/members:
    get:
      operationId: orgGroupMembers
      summary: A group's current members (any member of the company, or a superadmin)
      description: >
        Proxied to org's `/internal/org/groups/{id}/members`, with the same guard as the
        position holder read, so a guest member is refused with 403; a group of another company
        answers 404.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: The group's members
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/OrgGroupMember" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/companies/{companyId}/members/by-subject/{subject}:
    get:
      operationId: orgMemberBySubject
      summary: Membership fact for one subject (app backend or superadmin)
      description: >
        Fixed proxy to org's `/internal/org/companies/{companyId}/members/by-kcsub/{subject}`.
        A registered app's backend (client-credentials token whose `azp` is the app's service
        client id) or a superadmin asks whether `subject` is an active member of the company and
        which member record that is. Never a directory: one subject, one answer.
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: subject
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Membership fact
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      isMember: { type: boolean }
                      isActive: { type: boolean }
                      memberId: { type: string, format: uuid, nullable: true }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/auth/grants:
    post:
      operationId: authzGrants
      summary: Write authz tuples (superadmin, or a registered app on its own types)
      description: >
        Fixed proxy to authz's own `/internal/authz/grants` (internal/authz/http.go), the one
        write path exposed through the gateway for raw tuple grants. A superadmin may call it;
        so may a registered app's backend (a client-credentials token whose `azp` is the app's
        service client id), which authz then restricts to tuples on that app's own object types.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AuthzGrantsRequest" }
      responses:
        "200":
          description: Grant result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status: { type: string }
                      count: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422":
          description: A tuple names a base or unknown object type, or its object is not anchored to companyId (VALIDATION_FAILED)
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/platform-roles:
    post:
      operationId: superadminGrantPlatformRole
      summary: Grant the platform role (superadmin only)
      description: >
        Superadmin-gated fixed proxy to authz's own `POST /internal/authz/platform-roles`. The
        platform role's one record is the authz tuple `system:platform#superadmin @ user:<subjectId>`;
        authz writes it with its grant-ledger and audit rows in one transaction. The subject must
        already exist in identity (404 otherwise); `kiban-superadmin` is the only role (422 otherwise).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlatformRoleRequest" }
      responses:
        "200":
          description: Granted (idempotent for an existing holder)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/PlatformRoleRequest" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/platform-roles/{role}/{subjectId}:
    delete:
      operationId: superadminRevokePlatformRole
      summary: Revoke the platform role (superadmin only; the last superadmin cannot be revoked)
      description: >
        Superadmin-gated fixed proxy to authz's own `DELETE /internal/authz/platform-roles/{role}/{subjectId}`.
        404 when the subject does not hold the role; 409 CONFLICT when it is the platform's last
        superadmin (the caller revoking themselves included).
      parameters:
        - name: role
          in: path
          required: true
          schema: { type: string, enum: [kiban-superadmin] }
        - name: subjectId
          in: path
          required: true
          description: The subject's Keycloak subject id (kcSub).
          schema: { type: string }
      responses:
        "200":
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/PlatformRoleRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  # ---- platform_routes.go ----------------------------------------------------------------------
  /api/platform/capabilities:
    get:
      operationId: platformCapabilities
      summary: Capability state for every module (installed/enabled/dependencies)
      description: >
        Bearer-gated only (deliberately outside the superadmin gate, avoids a
        gateway<->authz cycle, platform_routes.go's own header comment). Fixed proxy to the
        registry service, path forwarded unchanged.
      responses:
        "200":
          description: One capability entry per known module
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Capability" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/platform/capabilities/{module}:
    get:
      operationId: platformCapabilityByModule
      summary: Capability state for one module
      parameters:
        - name: module
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The module's capability entry
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Capability" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/platform/catalog:
    get:
      operationId: platformCatalog
      summary: The full module catalog (metadata for every known module, not just capability state)
      responses:
        "200":
          description: Catalog entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/CatalogEntry" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/platform/admin/modules/{key}/enable:
    post:
      operationId: superadminEnableModule
      summary: Enable a module (superadmin only)
      description: Superadmin-gated fixed proxy, rewritten to the registry's own `/internal/platform/modules/{key}/enable`.
      parameters:
        - name: key
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      enabled: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/ModuleNotInstalled" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/apps:
    post:
      operationId: superadminRegisterApp
      summary: Register an app from its manifest (superadmin only)
      description: >
        Superadmin-gated fixed proxy to the registry's `/internal/platform/apps`. Registers (or
        re-registers) an app that runs beside Kiban: its object types and relations (the
        authorization fragment), its feature keys and the service client whose token identifies
        its backend. The app is installed at once and enabled per company with the enable route.
        No restart; the gateway never proxies to it.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AppManifest" }
      responses:
        "200":
          description: The app's capability state
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Capability" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/mfa-policy/global:
    get:
      operationId: superadminGetGlobalMfaPolicy
      summary: Read the realm-wide second-factor policy (superadmin only)
      description: >
        Superadmin-gated fixed proxy to identity's `/internal/identity/mfa-policy/global`. A new
        realm requires no second factor (`required: false`).
      responses:
        "200":
          description: The global policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/MfaPolicy" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    put:
      operationId: superadminSetGlobalMfaPolicy
      summary: Set the realm-wide second-factor policy (superadmin only)
      description: >
        Stores the policy. It reaches Keycloak on the next sync (`POST .../mfa-policy/sync`):
        run the sync after every policy change. `required: true` needs an enforceable method.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MfaPolicyRequest" }
      responses:
        "200":
          description: Stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      required: { type: boolean }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422":
          description: required without an enforceable method (VALIDATION_FAILED)
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/mfa-policy/users/{subject}:
    parameters:
      - name: subject
        in: path
        required: true
        description: The user's Keycloak subject (`sub`). The user must have signed in once.
        schema: { type: string }
    get:
      operationId: superadminGetUserMfaPolicy
      summary: Read a user's effective second-factor policy (superadmin only)
      description: The user's override when one is set, otherwise the global policy.
      responses:
        "200":
          description: The effective policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/MfaPolicy" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    put:
      operationId: superadminSetUserMfaPolicy
      summary: Set a user's second-factor override (superadmin only)
      description: >
        An override may only raise the requirement above the global policy, never lower it.
        Takes effect on the next sync.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MfaPolicyRequest" }
      responses:
        "200":
          description: Stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      required: { type: boolean }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422":
          description: required without an enforceable method, or weaker than the global policy (VALIDATION_FAILED)
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    delete:
      operationId: superadminClearUserMfaPolicy
      summary: Remove a user's second-factor override (superadmin only)
      responses:
        "200":
          description: Removed; the global policy applies again after the next sync
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/mfa-policy/sync:
    post:
      operationId: superadminSyncMfaPolicy
      summary: Push the stored second-factor policy to every Keycloak user (superadmin only)
      description: >
        Writes each user's effective policy to Keycloak, where the login flow enforces it. Run
        it after every policy change; safe to repeat.
      responses:
        "200":
          description: One outcome per user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/MfaSyncOutcome" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/admin/modules/{key}/disable:
    post:
      operationId: superadminDisableModule
      summary: Disable a module (superadmin only; mandatory modules refuse)
      parameters:
        - name: key
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Disabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      enabled: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/platform/metrics:
    get:
      operationId: platformMetrics
      summary: The platform's aggregated Prometheus exposition (operator-only, one scrape target)
      description: >
        The only metrics surface exposed through the gateway, behind the superadmin guard, and
        the single scrape target for the whole platform: the gateway's own registry merged with
        the `/metrics` of registry, identity, org, authz and every installed+enabled module,
        fetched concurrently on the internal network (2 s per target). Every series carries a
        `service="<name>"` label; metric families of the same name from several services share
        one `# HELP`/`# TYPE`. A target that fails or times out contributes only
        `kiban_metrics_scrape_up{service="<name>"} 0` (1 on success) — the response is always
        200, never a failed scrape. Plain-text Prometheus exposition format
        (`text/plain; version=0.0.4`), not JSON, documented here with no schema.
      responses:
        "200":
          description: Prometheus text exposition
          content:
            text/plain: {}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  # ---- admin_position_routes.go ----------------------------------------------------------------
  /api/org/admin/units:
    post:
      operationId: superadminCreateOrgUnit
      summary: Create a company or an org unit (superadmin only)
      description: >
        Superadmin-gated fixed proxy to org's `/internal/org/units`. A company is a unit with
        `typeKey` "company" and no parent; creating an active company also writes every enabled
        module's administrator relation for it in the same transaction. Any other unit names its
        parent. Codes are normalised to upper case.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/OrgUnitCreateRequest" }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgUnit" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/units/{id}:
    get:
      operationId: superadminGetOrgUnit
      summary: Read one org unit (superadmin only)
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: The unit
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgUnit" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/units/{id}/subtree:
    get:
      operationId: superadminOrgUnitSubtree
      summary: The unit and every unit below it (superadmin only)
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: Units, the root first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/OrgUnit" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/members:
    post:
      operationId: superadminCreateMember
      summary: Create a member in a company (superadmin, or an administrator of the company)
      description: >
        Superadmin-gated fixed proxy to org's `/internal/org/members`. The member has no login
        until it is linked to a subject with the link-user route.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/OrgMemberCreateRequest" }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgMember" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    get:
      operationId: superadminListMembers
      summary: List a company's members (superadmin, or an administrator of the company)
      parameters:
        - { name: companyId, in: query, required: true, schema: { type: string, format: uuid } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
      responses:
        "200":
          description: Page of members
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/OrgMember" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/members/{id}:
    put:
      operationId: superadminUpdateMember
      summary: Update a member (superadmin, or an administrator of the company)
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/OrgMemberUpdateRequest" }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgMember" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/members/{id}/link-user:
    post:
      operationId: superadminLinkMemberUser
      summary: Link a member to a login subject (superadmin, or an administrator of the company)
      description: >
        `kcSub` is the subject's `sub` claim; the identity record exists once that subject has
        made one request through the gateway. A subject is linked to at most one member per company.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kcSub]
              properties:
                kcSub: { type: string }
      responses:
        "200":
          description: Linked
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgMember" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    delete:
      operationId: superadminUnlinkMemberUser
      summary: Unlink a member from its login subject (superadmin, or an administrator of the company)
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: Unlinked
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgMember" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/companies/{companyId}/positions:
    get:
      operationId: adminListPositions
      summary: List a company's positions, each with its current holder (superadmin, or an administrator of the company)
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: "Page of positions with holder (the paginated envelope, not a bare array; same shape as adminListGroups)"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/OrgPositionWithHolder" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    post:
      operationId: adminCreatePosition
      summary: Create a position (superadmin, or an administrator of the company)
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, title]
              properties:
                code: { type: string }
                title: { type: string }
                orgUnitId:
                  type: string
                  format: uuid
                  description: An org unit under the company; absent, the company root.
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgPosition" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/positions/{id}:
    put:
      operationId: adminUpdatePosition
      summary: Retitle a position or move it to another org unit of its company (superadmin, or an administrator of the company)
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
                orgUnitId:
                  type: string
                  format: uuid
                  description: An org unit under the position's company; absent, unchanged.
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgPosition" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
  /api/org/admin/positions/{id}/assignments:
    post:
      operationId: adminAssignPositionNow
      summary: Assign a member to a position, effective now (superadmin, or an administrator of the company)
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [memberId]
              properties:
                memberId: { type: string, format: uuid }
      responses:
        "201":
          description: Assignment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgAssignment" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/PositionHeld" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/positions/{id}/handover:
    post:
      operationId: adminHandoverPosition
      summary: Hand a held position to another member in one step (superadmin, or an administrator of the company)
      description: >
        Ends the current assignment and creates the new one in one transaction, so no check
        between the two finds the position empty. An empty position is a 422 (assign instead);
        a stale `expectedAssignmentId` is a 409 so two administrators cannot hand the same
        chair over twice; handing it to the current holder changes nothing and answers 200.
        Both audit events carry the same `handoverId`.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [memberId]
              properties:
                memberId: { type: string, format: uuid }
                expectedAssignmentId: { type: string, format: uuid, description: "The assignment the caller believes is current; 409 when it is not." }
      responses:
        "200":
          description: The ended assignment and the new one
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgHandover" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/PositionHeld" }
        "422":
          description: The position has no current holder (VALIDATION_ERROR); assign instead
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/assignments/{id}/end:
    post:
      operationId: adminEndAssignmentNow
      summary: End a position assignment, effective now (superadmin, or an administrator of the company, no body, server-dated)
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Assignment ended
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgAssignment" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: ASSIGNMENT_ALREADY_ENDED, the assignment's validTo is already set; nothing is written
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  # ---- admin_group_routes.go --------------------------------------------------------------------
  /api/org/admin/companies/{companyId}/groups:
    get:
      operationId: adminListGroups
      summary: List a company's groups, each with its current member count (superadmin, or an administrator of the company)
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: "Page of groups with member count (the paginated envelope, not a bare array; same shape as adminListPositions)"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items: { $ref: "#/components/schemas/OrgGroupWithMemberCount" }
                      total: { type: integer }
                      page: { type: integer }
                      pageSize: { type: integer }
                      totalPages: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    post:
      operationId: adminCreateGroup
      summary: Create a group (superadmin, or an administrator of the company; source is always "kiban" through this route)
      parameters:
        - name: companyId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, name]
              properties:
                code: { type: string }
                name: { type: string }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgGroup" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/groups/{id}/members:
    get:
      operationId: adminListGroupMembers
      summary: List a group's current members (superadmin, or an administrator of the company)
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Group members
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/OrgGroupMember" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }
    post:
      operationId: adminAddGroupMember
      summary: Add a member to a group (superadmin, or an administrator of the company; 409 if the group is not source="kiban")
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [memberId]
              properties:
                memberId: { type: string, format: uuid }
      responses:
        "201":
          description: Added
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/OrgGroupMember" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/GroupExternallyManaged" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

  /api/org/admin/groups/{id}/members/{memberId}:
    delete:
      operationId: adminRemoveGroupMember
      summary: Remove a member from a group (superadmin, or an administrator of the company; 409 if the group is not source="kiban")
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: memberId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Removed (200 with the removed pair, not 204)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      groupId: { type: string, format: uuid }
                      memberId: { type: string, format: uuid }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/GroupExternallyManaged" }
        "503": { $ref: "#/components/responses/AuthorizationUnavailable" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        A Kiban access token: a user's, from a browser login through the gateway's /auth proxy
        (client kiban-frontend, PKCE), or a service client's, from the client-credentials grant
        (KIBAN_SERVICE_CLIENTS). Audience kiban-api, issuer <gateway>/realms/kiban.
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
            details: {}

    MfaPolicy:
      type: object
      required: [required]
      properties:
        required: { type: boolean }
        method:
          type: string
          nullable: true
          description: "`otp` (authenticator app), `passkey`, or `otp_or_passkey`; absent when not required."

    MfaPolicyRequest:
      type: object
      required: [required]
      properties:
        required: { type: boolean }
        method:
          type: string
          enum: [otp, passkey, otp_or_passkey]
          description: Required when `required` is true.

    MfaSyncOutcome:
      type: object
      description: One user's sync result.
      properties:
        UserID: { type: string }
        KcSub: { type: string }
        Required: { type: boolean }
        RequiredMode: { type: string, description: "The mode written to Keycloak: `none`, `otp_required`, `passkey_required` or `otp_or_passkey_required`." }
        Success: { type: boolean }
        Error: { type: string }

    PlatformRoleRequest:
      type: object
      required: [subjectId, role]
      properties:
        subjectId: { type: string, description: The subject's Keycloak subject id (kcSub). }
        role: { type: string, enum: [kiban-superadmin] }

    EffectiveAccessObjectRef:
      type: object
      required: [type, id]
      additionalProperties: false
      properties:
        type: { type: string }
        id: { type: string }

    EffectiveAccessRequest:
      type: object
      required: [featureKey, scope]
      properties:
        featureKey: { type: string }
        moduleKey: { type: string }
        scope: { type: string, enum: [global, company] }
        companyId: { type: string, format: uuid }
        requiredPlatformRole: { type: string }
        allowPlatformOperatorCompanyScope: { type: boolean }
        requiredCompanyRole: { type: string }
        object: { $ref: "#/components/schemas/EffectiveAccessObjectRef" }
        relation: { type: string }
        requiresEligibility: { type: boolean }
        correlationId: { type: string }

    EffectiveAccessEvidence:
      type: object
      properties:
        key: { type: string }
        value: { type: string }

    EffectiveAccessDecision:
      type: object
      properties:
        allowed: { type: boolean }
        reason: { type: string }
        evidence:
          type: array
          items: { $ref: "#/components/schemas/EffectiveAccessEvidence" }

    EffectiveAccessDecisionEnvelope:
      type: object
      properties:
        data: { $ref: "#/components/schemas/EffectiveAccessDecision" }

    EffectiveAccessBatchRequest:
      type: object
      required: [items]
      properties:
        items:
          type: array
          maxItems: 100
          items:
            type: object
            required: [object, relation]
            properties:
              object: { $ref: "#/components/schemas/EffectiveAccessObjectRef" }
              relation: { type: string }

    EffectiveAccessBatchEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              object: { $ref: "#/components/schemas/EffectiveAccessObjectRef" }
              relation: { type: string }
              decision: { $ref: "#/components/schemas/EffectiveAccessDecision" }

    EffectiveAccessRoleBinding:
      type: object
      properties:
        scope: { type: string, enum: [global, company] }
        role: { type: string }
        companyId: { type: string, format: uuid }

    EffectiveAccessObjectAccessEntry:
      type: object
      properties:
        objectType: { type: string }
        objectId: { type: string }
        relations:
          type: array
          items: { type: string }

    EffectiveAccessSummary:
      type: object
      properties:
        data:
          type: object
          properties:
            apiVersion: { type: integer }
            subjectId: { type: string }
            companyId: { type: string }
            moduleKey: { type: string }
            featureKeys:
              type: array
              items: { type: string }
            roleBindings:
              type: array
              items: { $ref: "#/components/schemas/EffectiveAccessRoleBinding" }
            objectAccess:
              type: array
              items: { $ref: "#/components/schemas/EffectiveAccessObjectAccessEntry" }
            rowScopes: { type: array, items: {} }
            fieldPolicies: { type: array, items: {} }

    AppManifest:
      type: object
      required: [key, displayName, version, serviceClientId, authzFragment]
      properties:
        key: { type: string, pattern: "^[a-z][a-z0-9_]{1,31}$" }
        displayName: { type: string }
        version: { type: string }
        serviceClientId: { type: string, pattern: "^[a-z][a-z0-9_-]{1,63}$" }
        features:
          type: array
          items: { type: string }
        authzFragment:
          type: object
          description: The fragment's "relations" section, one entry per object type
          additionalProperties: true
    AuthzGrantsRequest:
      type: object
      required: [op, companyId, tuples]
      description: >
        Every tuple is bound to `companyId`: its object must be an object type declared by one
        enabled module's fragment (anchored to `company_module:<companyId>/<module>`, an anchor
        tuple in the same grant request counts) or `company_module:<companyId>/<module>` itself;
        base types (company, system, module, member, position, group) are refused (422), with
        one exception: a superadmin may grant or revoke `company:<companyId>#admin` for a user,
        which appoints or dismisses an administrator of that company. Otherwise the bearer must
        pass the effective-access decision's steps 1–6 for that (module, company) (403
        otherwise) and, for a `company_module` object, hold its `admin` relation.
      properties:
        op: { type: string, enum: [grant, revoke] }
        companyId: { type: string, format: uuid }
        correlationId: { type: string }
        tuples:
          type: array
          items:
            type: object
            required: [objectType, objectId, relation, subjectType, subjectId]
            properties:
              objectType: { type: string }
              objectId: { type: string }
              relation: { type: string }
              subjectType: { type: string }
              subjectId: { type: string }
              subjectRelation: { type: string }

    OrgMeCompany:
      type: object
      properties:
        id: { type: string, format: uuid }
        code: { type: string }
        name: { type: string }
        isActive: { type: boolean }

    MemberDirectoryEntry:
      type: object
      properties:
        id: { type: string, format: uuid }
        displayName: { type: string }
        email: { type: string }
        hasLinkedUser: { type: boolean }
        kind: { type: string, enum: [person, service], description: "`service` when the linked user is an app's service account" }

    PositionDirectoryEntry:
      type: object
      properties:
        id: { type: string, format: uuid }
        code: { type: string }
        title: { type: string }

    GroupDirectoryEntry:
      type: object
      properties:
        id: { type: string, format: uuid }
        code: { type: string }
        name: { type: string }

    Capability:
      type: object
      properties:
        module: { type: string }
        installed: { type: boolean }
        enabled: { type: boolean }
        dependencies: { type: array, items: { type: string } }
        missingDependencies: { type: array, items: { type: string } }

    CatalogEntry:
      type: object
      properties:
        moduleKey: { type: string }
        displayName: { type: string }
        scopeType: { type: string }
        mandatory: { type: boolean }
        basePath: { type: string }
        healthPath: { type: string }
        port: { type: integer }
        licenseClass: { type: string }
        manifestVersion: { type: string }
        isActive: { type: boolean }

    OrgUnit:
      type: object
      properties:
        id: { type: string, format: uuid }
        typeKey: { type: string }
        parentId: { type: string, format: uuid, nullable: true }
        code: { type: string }
        name: { type: string }
        isActive: { type: boolean }
    OrgUnitCreateRequest:
      type: object
      required: [typeKey, code, name]
      properties:
        typeKey: { type: string, description: "\"company\" for a company; a taxonomy key such as \"business_unit\" below it" }
        parentId: { type: string, format: uuid, nullable: true }
        code: { type: string }
        name: { type: string }
    OrgMember:
      type: object
      properties:
        id: { type: string, format: uuid }
        companyId: { type: string, format: uuid }
        code: { type: string }
        displayName: { type: string }
        email: { type: string, nullable: true }
        userId: { type: string, nullable: true, description: "The linked identity user, or null" }
        isActive: { type: boolean }
        isGuest: { type: boolean, description: "An external person the company shares objects with: a member for every decision, refused the directories" }
        kind: { type: string, enum: [person, service], description: "`service` when the linked user is an app's service account; `person` otherwise" }
    OrgMemberCreateRequest:
      type: object
      required: [companyId, code, displayName]
      properties:
        companyId: { type: string, format: uuid }
        code: { type: string }
        displayName: { type: string }
        email: { type: string }
        isGuest: { type: boolean, default: false }
    OrgMemberUpdateRequest:
      type: object
      properties:
        displayName: { type: string }
        email: { type: string }
        isActive: { type: boolean }
        isGuest: { type: boolean, description: "Absent keeps the current value" }
    OrgPosition:
      type: object
      properties:
        id: { type: string, format: uuid }
        companyId: { type: string, format: uuid }
        code: { type: string }
        title: { type: string }
        orgUnitId: { type: string, format: uuid }

    OrgPositionWithHolder:
      allOf:
        - $ref: "#/components/schemas/OrgPosition"
        - type: object
          properties:
            assignmentId: { type: string, format: uuid, nullable: true }
            memberId: { type: string, format: uuid, nullable: true }
            holderDisplayName: { type: string, nullable: true }

    OrgAssignment:
      type: object
      properties:
        id: { type: string, format: uuid }
        positionId: { type: string, format: uuid }
        memberId: { type: string, format: uuid }
        validFrom: { type: string, format: date, description: "Plain date (YYYY-MM-DD), not date-time." }
        validTo: { type: string, format: date, nullable: true, description: "Plain date (YYYY-MM-DD), not date-time." }

    OrgHandover:
      type: object
      properties:
        ended: { allOf: [ { $ref: "#/components/schemas/OrgAssignment" } ], nullable: true, description: "Null when the member already held the position." }
        assignment: { $ref: "#/components/schemas/OrgAssignment" }

    OrgGroup:
      type: object
      properties:
        id: { type: string, format: uuid }
        companyId: { type: string, format: uuid }
        code: { type: string }
        name: { type: string }
        source: { type: string }
        externalRef: { type: string, nullable: true }
        isActive: { type: boolean }
        isKibanManaged: { type: boolean }

    OrgGroupWithMemberCount:
      allOf:
        - $ref: "#/components/schemas/OrgGroup"
        - type: object
          properties:
            memberCount: { type: integer }

    OrgGroupMember:
      type: object
      properties:
        groupId: { type: string, format: uuid }
        memberId: { type: string, format: uuid }
        addedBy: { type: string }
        addedAt: { type: string, format: date-time }
        memberDisplayName: { type: string }
        memberEmail: { type: string, nullable: true }

  responses:
    BadRequest:
      description: BAD_REQUEST / VALIDATION_ERROR
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    Unauthorized:
      description: AUTH_TOKEN_MISSING / AUTH_TOKEN_INVALID
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    Forbidden:
      description: FORBIDDEN / AUTHORIZATION_DENIED / PLATFORM_ROLE_REQUIRED (RequireSuperadmin denial)
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    NotFound:
      description: NOT_FOUND
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    Conflict:
      description: CONFLICT (e.g. disabling a mandatory module, revoking the last superadmin)
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    PositionHeld:
      description: >
        POSITION_HELD, the position has a holder today; `details.assignmentId` and
        `details.memberId` name the current assignment to end first.
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    ModuleNotInstalled:
      description: >
        MODULE_NOT_INSTALLED, the module's installation row has `installed=false`; enable is
        refused and nothing is written (no fragment activation, no default grants, no audit row).
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    ValidationFailed:
      description: VALIDATION_FAILED, a domain-policy rejection distinct from ordinary field-shape validation
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    GroupExternallyManaged:
      description: >
        GROUP_EXTERNALLY_MANAGED, the group's `source` is not "kiban"; membership is read-only
        through every human/API path (the single-writer-by-provenance
        invariant, enforced in org's STORE layer, not only the HTTP handler).
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    AuthorizationUnavailable:
      description: >
        AUTHORIZATION_UNAVAILABLE, authz (or another required dependency) could not be reached;
        fail-closed, never a stale allow.
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
