UNPKG

@fntio/infra-client

Version:

Self-hosted AWS access portal: credential vending, target-account trust, and grant-driven private networking as CDK stacks and constructs.

4,624 lines • 205 kB
# The HTTP contract of the portal API — every route the Express app mounts.
# lambdacode/api/__tests__/openapi.test.ts fails when a mounted route is
# missing here (or a documented one is gone), so this file cannot go stale.
# The private dev repo generates its Postman collection FROM this file.
openapi: 3.1.0
info:
  title: Infra Client API
  version: 0.8.0
  summary: Self-hosted AWS access portal — credential vending, access requests, admin catalog, private-network resources.
  description: |
    One Express app behind CloudFront (`/api/*`) and API Gateway (no prefix).

    ## Authentication

    Every route except `GET /health` and `GET /.well-known/infra-client` takes
    `Authorization: Bearer <token>`, where the token is one of:

    - **Human** — a Cognito **ID token** from the portal's user pool (in-app sign-in).
      Admin routes additionally require membership of the `admins` group
      (`cognito:groups` claim).
    - **Service user** — a Cognito **access token** minted with the
      `client_credentials` grant by an app client an admin created under
      *Admin → Service users*. It carries the `api/invoke` scope; its `sub` is
      the client id. Which routes it may call are the **scopes on its registry
      row**, chosen by the admin and read on every request: `aws`, `network` and
      `shares` as for personal access tokens below, plus `admin.read.all` (the
      `GET` routes under `/admin`) and `admin.write.all` (every route under
      `/admin`, reads included), with the same `403` / `code: "TOKEN_SCOPE"`
      outside them. The admin scopes make it an **app admin** for those methods
      — an `admin.write.all` service user manages users and service users like a
      human admin. Its AWS roles and network resources are ordinary grants with
      the client id as the `userId`. Service users created before scopes existed
      carry the full set (`aws`, `network`, `shares`, `admin.write.all`), which
      reaches the `/admin`, vending, device-key and share routes; routes outside
      that table (`/requests`, `/notifications`, `/preferences`, `/resources`,
      `/plugins`) are reachable by no service user. No service user calls the
      token routes.
    - **Personal access token** — `icpat_<tokenId>_<secret>`, created by a user on their
      *Access tokens* page (`POST /tokens`, signed-in session only) for scripts, CI jobs and
      command-line tools. It acts as its owner, limited to its scopes: `aws` (`GET /accounts`,
      `POST /credentials`, console links), `network` (`GET /network`, device keys, list/remove own
      devices), `shares` (`GET /network`, dev shares) or `api` (every route the owner may call —
      admin routes only while the owner is an admin). A route outside the scopes answers `403` with
      `code: "TOKEN_SCOPE"`; a wrong, expired or revoked token — or one whose owner is disabled — is a
      `401`. No token can call the token routes (`/tokens`, `/admin/tokens`) except
      `GET /tokens/current`, and none reaches plugin routes. Off unless the deployment sets
      `personalAccessTokens.enabled` (discovery says so).

    Token exchange for service users (see the Access Model wiki page, "Service users"):

        POST https://<cognito domain>/oauth2/token
        Authorization: Basic base64(clientId:clientSecret)
        Content-Type: application/x-www-form-urlencoded

        grant_type=client_credentials&scope=api/invoke

    ## Conventions

    - Errors are always JSON `{ "message": "…" }`. `401` = no/invalid token,
      `403` = not an admin (or no grant on a vend), `404` = addressed thing
      missing, `409` = already exists / still in use / already decided,
      `400` = malformed input, `501` = feature not deployed (private network,
      branding storage), `502` = a downstream AWS call failed.
    - Timestamps are ISO-8601 strings in UTC.
    - `accountNumber` is always the 12-digit AWS account id.
    - `userId` is the Cognito `sub` for humans and the app client id for
      service users — both are valid grant principals everywhere a `userId`
      path parameter appears.
    - Lists are returned whole; there is no server-side paging.
    - Temporary access uses the duration presets `1, 12, 24, 72, 168, 720`
      hours (1 h … 30 d). Omitting the duration means long-term (standing) access.
  license:
    name: Elastic License 2.0
    identifier: Elastic-2.0
servers:
  - url: https://{host}/api
    description: Through the portal's CloudFront distribution (the web domain in your project config).
    variables:
      host:
        default: portal.example.com
        description: Your deployment's web domain.
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Liveness and the public discovery document.
  - name: Access
    description: What the caller may assume, and vending credentials or a console sign-in for it.
  - name: Requests
    description: The caller's own access requests (raising, listing, acknowledging decisions).
  - name: Preferences
    description: The caller's per-role and network preferences.
  - name: Network
    description: Private-network (VPN) sites and device enrollment.
  - name: Resources
    description: Private-network resources the caller can reach.
  - name: Notifications
    description: The caller's revoked-access notices (the bell).
  - name: Tokens
    description: Personal access tokens for scripts, CI jobs and command-line tools that act as the user.
  - name: "Admin: setup"
    description: First-run checklist state and branding.
  - name: "Admin: accounts & roles"
    description: The catalog of AWS accounts and the roles registered in them.
  - name: "Admin: grants"
    description: Who holds which role, directly or via groups.
  - name: "Admin: users"
    description: The Cognito directory and per-user cascades.
  - name: "Admin: tokens"
    description: Every user's personal access tokens.
  - name: "Admin: service users"
    description: Machine-to-machine app clients (client_credentials) and their scopes.
  - name: "Admin: groups"
    description: Role/resource bundles whose members inherit the bundle.
  - name: "Admin: requests"
    description: The approval queue and history.
  - name: "Admin: resources"
    description: Private-network resource catalog and resource grants.
  - name: "Admin: network"
    description: Site topology and the grants→ACL reconciler.
  - name: "Admin: audit"
    description: The vend / console / device-key event log.
  - name: Plugins
    description: What the signed-in caller may open, for the portal's own navigation.
  - name: "Admin: plugins"
    description: Every installed plugin definition, and who may use each binding.

paths:
  /health:
    get:
      tags: [Health]
      summary: Liveness
      operationId: health
      security: []
      responses:
        "200":
          description: The API is up.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean, const: true }
                required: [ok]

  /.well-known/infra-client:
    get:
      tags: [Health]
      summary: Discovery document (public)
      operationId: discovery
      description: |
        What the desktop app reads to self-configure from a deployment URL:
        the project name, the Cognito pool/client ids the SPA already ships
        with, the OIDC issuer, and the VPN control planes. Never secrets.
      security: []
      responses:
        "200":
          description: Discovery document.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Discovery" }

  /accounts:
    get:
      tags: [Access]
      summary: List my access
      operationId: listAccess
      description: |
        Accounts and roles the caller may assume right now (direct and group-provided grants, expired ones excluded), each with its resolved `~/.aws` profile name.
        With `limit`, one page of the list contract: sorts `position` (the admin order, default), `name`, `number`; facets `environment`, `main` (`true`/`false` — whether the account sits in the dashboard's Main section), `favorite` (`true`/`false` — the caller's own favorites), plus `tenant`, `project`, `stage` on a deployment with account dimensions (`unclassified` for an account without one).
        Each account carries `main: false` only when an admin took it off the Main section.
      parameters:
        - $ref: "#/components/parameters/listQ"
        - $ref: "#/components/parameters/listFilter"
        - $ref: "#/components/parameters/listSort"
        - $ref: "#/components/parameters/listLimit"
        - $ref: "#/components/parameters/listCursor"
      responses:
        "200":
          description: The caller's accounts — the whole list, or one page when `limit` was passed.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items: { $ref: "#/components/schemas/AccountAccess" }
                    required: [accounts]
                  - $ref: "#/components/schemas/AccountAccessPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /accounts/home:
    get:
      tags: [Access]
      summary: My dashboard
      operationId: homeAccess
      description: |
        The caller's access cut into the dashboard's shortcuts. `sectioned` is true once the caller holds an account
        that is not main (or whenever `layout` is `sections`); until then `main` is the whole list and the dashboard
        shows no sections. A caller who holds nothing is never sectioned, whatever the layout. Accounts the caller
        holds nothing in are not listed: asking for one is `GET /requests/catalog`'s job.
      responses:
        "200":
          description: The dashboard.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sectioned: { type: boolean }
                  heldTotal: { type: integer, minimum: 0 }
                  main: { type: array, items: { $ref: "#/components/schemas/AccountAccess" } }
                  favorites: { type: array, items: { $ref: "#/components/schemas/AccountAccess" } }
                  recent: { type: array, items: { $ref: "#/components/schemas/AccountAccess" }, description: Newest first. }
                  favoriteNumbers: { type: array, items: { $ref: "#/components/schemas/AccountNumber" } }
                  layout: { type: string, enum: [auto, sections, plain], description: The deployment's configured `dashboard.layout` behind `sectioned` (auto = sections once a held account is off the Main section). }
                required: [sectioned, heldTotal, main, favorites, recent, favoriteNumbers, layout]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /accounts/names:
    get:
      tags: [Access]
      summary: Friendly names of every registered account
      operationId: listAccountNames
      description: |
        Account number → admin-set name, for every registered account that has one — the label lookup the web app
        binds on chips and rows. Catalog facts only, never roles or holders; a few dozen KB where the full catalog is
        megabytes. Every signed-in user may read it (the request catalog already shows every account).
      responses:
        "200":
          description: The name map.
          content:
            application/json:
              schema:
                type: object
                properties:
                  names:
                    type: object
                    additionalProperties: { type: string }
                required: [names]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
  /accounts/expiry:
    get:
      tags: [Access]
      summary: My expiry notices
      operationId: listExpiryNotices
      description: The caller's temporary role grants nearing (`expiring`) or past (`expired`) their end — the bell feed.
      responses:
        "200":
          description: Expiry notices by phase.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExpiryNotices" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /accounts/expiry/seen:
    post:
      tags: [Access]
      summary: Acknowledge expiry notices
      operationId: markExpiryNoticesSeen
      responses:
        "200":
          description: How many notices were newly marked seen.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Cleared" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /accounts/{accountNumber}/roles/{roleName}/console:
    post:
      tags: [Access]
      summary: Console sign-in URL
      operationId: consoleSignIn
      description: |
        "Go to Console": same grant check as `POST /credentials`, returns a
        short-lived AWS console federation URL. Every call — vended, denied or
        failed — writes an audit event.
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                destination:
                  type: string
                  format: uri
                  description: Optional post-login destination; must be an `https://…console.aws.amazon.com/` URL.
            example: { destination: "https://eu-central-1.console.aws.amazon.com/s3/home" }
      responses:
        "200":
          description: The sign-in URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ConsoleSignIn" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403":
          description: No active grant for this role (`NO_GRANT` or `EXPIRED`), or the role is no longer in the catalog (`NO_ROLE`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "502": { $ref: "#/components/responses/Upstream" }

  /credentials:
    post:
      tags: [Access]
      summary: Vend credentials
      operationId: vendCredentials
      description: |
        Temporary AWS credentials for a role the caller holds. The session
        length is the role's `sessionDurationSeconds` (default 3600), capped
        by the IAM role's MaxSessionDuration — a cap violation is a `502`
        whose message says so. Every call writes an audit event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountNumber: { $ref: "#/components/schemas/AccountNumber" }
                role:
                  type: string
                  maxLength: 128
                  description: The role name (not the ARN). May not contain `#` or `/`.
                background:
                  type: boolean
                  description: "true = an automatic renewal (desktop keep-fresh), which does not count as the person reaching for the account: it leaves the dashboard's Recent section alone."
              required: [accountNumber, role]
            example: { accountNumber: "123456789012", role: "ReadOnly" }
      responses:
        "200":
          description: Credentials.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VendedCredentials" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403":
          description: No active grant for this role (`NO_GRANT` or `EXPIRED`), or the role is no longer in the catalog (`NO_ROLE`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "502": { $ref: "#/components/responses/Upstream" }

  /requests/catalog:
    get:
      tags: [Requests]
      summary: Requestable roles
      operationId: listRequestableRoles
      description: |
        The role catalog minus what the caller already holds long-term or has pending. Account numbers and role names only — never ARNs or holders.
        With `limit`, one page of the list contract: sorts `name` (default), `number`; facets `tenant`, `project`, `stage` on a deployment with account dimensions (`unclassified` for an account without one), none otherwise.
      parameters:
        - $ref: "#/components/parameters/listQ"
        - $ref: "#/components/parameters/listFilter"
        - $ref: "#/components/parameters/listSort"
        - $ref: "#/components/parameters/listLimit"
        - $ref: "#/components/parameters/listCursor"
      responses:
        "200":
          description: Accounts with requestable roles — the whole list, or one page when `limit` was passed.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items: { $ref: "#/components/schemas/RequestableAccount" }
                    required: [accounts]
                  - $ref: "#/components/schemas/RequestableAccountPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /requests/resource-catalog:
    get:
      tags: [Requests]
      summary: Requestable resources
      operationId: listRequestableResources
      description: Private-network resources the caller may ask for — name, type, description and account only; connection details appear only after a grant (`GET /resources`).
      responses:
        "200":
          description: Requestable resources.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items: { $ref: "#/components/schemas/RequestableResource" }
                required: [resources]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /requests:
    get:
      tags: [Requests]
      summary: My requests
      operationId: listMyRequests
      description: The caller's own requests, newest first. Resource rows carry a resolved `resourceName`.
      responses:
        "200":
          description: The caller's requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requests:
                    type: array
                    items: { $ref: "#/components/schemas/AccessRequest" }
                required: [requests]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: [Requests]
      summary: Request a role
      operationId: createRequest
      description: Ask for a role. The requester is always the caller. `409` if the caller already holds it long-term or has one pending; `404` if the role is not catalogued.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountNumber: { $ref: "#/components/schemas/AccountNumber" }
                roleName: { type: string }
                reason: { type: string, maxLength: 500 }
                durationHours: { $ref: "#/components/schemas/DurationHours" }
              required: [accountNumber, roleName]
            example: { accountNumber: "123456789012", roleName: "ReadOnly", reason: "Investigating an incident", durationHours: 24 }
      responses:
        "201":
          description: The pending request.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RequestEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /requests/resource:
    post:
      tags: [Requests]
      summary: Request a resource
      operationId: createResourceRequest
      description: Ask for private-network access to one resource. Same rules as requesting a role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceId: { type: string }
                reason: { type: string, maxLength: 500 }
                durationHours: { $ref: "#/components/schemas/DurationHours" }
              required: [resourceId]
            example: { resourceId: "7f1c2b3a-0000-4000-8000-000000000000", reason: "Need the staging database", durationHours: 72 }
      responses:
        "201":
          description: The pending request.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RequestEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /requests/seen:
    post:
      tags: [Requests]
      summary: Acknowledge decisions
      operationId: markRequestsSeen
      description: Marks the caller's decided requests as seen (clears the bell badge).
      responses:
        "200":
          description: How many requests were newly marked seen.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Cleared" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences:
    get:
      tags: [Preferences]
      summary: List my role preferences
      operationId: listPreferences
      description: Every (account, role) the caller has customised — profile-name override, role label, auto-vend star.
      responses:
        "200":
          description: Preference rows.
          content:
            application/json:
              schema:
                type: object
                properties:
                  preferences:
                    type: array
                    items: { $ref: "#/components/schemas/RolePreference" }
                required: [preferences]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/auto-vend/{accountNumber}/{role}:
    put:
      tags: [Preferences]
      summary: Set the auto-vend star
      operationId: setAutoVend
      description: Starred roles are vended silently on app load (desktop keeps them fresh in `~/.aws/credentials`).
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                autoVend: { type: boolean }
              required: [autoVend]
            example: { autoVend: true }
      responses:
        "200":
          description: The saved value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  autoVend: { type: boolean }
                required: [autoVend]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/favorites/{accountNumber}:
    put:
      tags: [Preferences]
      summary: Star or unstar an account
      operationId: setFavorite
      description: A starred account shows in the dashboard's Favorites section on every device. At most 50; starring a starred account changes nothing.
      parameters:
        - $ref: "#/components/parameters/accountNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                favorite: { type: boolean }
              required: [favorite]
      responses:
        "200":
          description: The saved state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  favorite: { type: boolean }
                required: [favorite]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/network:
    get:
      tags: [Preferences]
      summary: Get my network preferences
      operationId: getNetworkPrefs
      description: Device-independent VPN preferences — the auto-reconnect toggle and the site a reconnect rejoins.
      responses:
        "200":
          description: Network preferences.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/NetworkPrefs" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    put:
      tags: [Preferences]
      summary: Update my network preferences
      operationId: setNetworkPrefs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one field.
              properties:
                autoReconnect: { type: boolean }
                lastSiteId: { type: string, minLength: 1, maxLength: 64 }
            example: { autoReconnect: true, lastSiteId: "dev" }
      responses:
        "200":
          description: The preferences after the update.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/NetworkPrefs" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/notifications:
    get:
      tags: [Preferences]
      summary: Get my notification preferences
      operationId: getNotificationPrefs
      description: Which bell items may pop up as native notifications (desktop toasts, browser notifications). Everything is on until turned off; the row follows the user across devices.
      responses:
        "200":
          description: Notification preferences.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/NotificationPrefs" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    put:
      tags: [Preferences]
      summary: Update my notification preferences
      operationId: setNotificationPrefs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one field; `kinds` may be partial.
              properties:
                enabled: { type: boolean }
                kinds:
                  type: object
                  additionalProperties: { type: boolean }
            example: { enabled: true, kinds: { requests: false } }
      responses:
        "200":
          description: The preferences after the update.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/NotificationPrefs" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/profile-name/{accountNumber}/{role}:
    get:
      tags: [Preferences]
      summary: Get my profile-name override
      operationId: getProfileName
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      responses:
        "200":
          description: The override, or `null` when the admin default applies.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProfileNameValue" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    put:
      tags: [Preferences]
      summary: Set my profile-name override
      operationId: setProfileName
      description: A blank or absent `profileName` clears the override (same as DELETE).
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profileName: { type: string, maxLength: 128 }
            example: { profileName: "acme-prod-readonly" }
      responses:
        "200":
          description: The saved value (`null` when cleared).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProfileNameValue" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: [Preferences]
      summary: Clear my profile-name override
      operationId: clearProfileName
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      responses:
        "204": { description: Cleared. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /preferences/role-label/{accountNumber}/{role}:
    put:
      tags: [Preferences]
      summary: Set my role label
      operationId: setRoleLabel
      description: A personal display name for the role card. Blank or absent clears it (the admin display name shows again).
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                roleLabel: { type: string, maxLength: 64 }
            example: { roleLabel: "Prod read-only" }
      responses:
        "200":
          description: The saved value (`null` when cleared).
          content:
            application/json:
              schema:
                type: object
                properties:
                  roleLabel: { type: [string, "null"] }
                required: [roleLabel]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: [Preferences]
      summary: Clear my role label
      operationId: clearRoleLabel
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/role"
      responses:
        "204": { description: Cleared. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network:
    get:
      tags: [Network]
      summary: Network sites
      operationId: listNetworkSites
      description: Whether private-network access is deployed, and the sites a device may enrol in. Split-DNS and VPC detail are admin-only (`GET /admin/network`).
      responses:
        "200":
          description: Site list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled: { type: boolean }
                  controlUrl:
                    type: [string, "null"]
                    description: Legacy single-site field — always the first site's control URL.
                  sites:
                    type: array
                    items: { $ref: "#/components/schemas/PublicSite" }
                  devShares:
                    type: object
                    description: Whether dev shares can be created, the longest one allowed, and how many live shares one user may hold.
                    properties:
                      enabled: { type: boolean }
                      maxDurationHours: { type: integer, minimum: 1, maximum: 72 }
                      maxActiveSharesPerOwner: { type: integer, minimum: 1, maximum: 200 }
                    required: [enabled, maxDurationHours, maxActiveSharesPerOwner]
                required: [enabled, controlUrl, sites, devShares]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }

  /network/device-key:
    post:
      tags: [Network]
      summary: Mint a device enrollment key
      operationId: mintDeviceKey
      description: |
        A single-use, 30-minute enrollment key for ONE site, bound to the
        caller's identity (their `sub` becomes the device's network user).
        Reachability is enforced by the grants→ACL reconciler, not here.
        Every mint writes an audit event (`NETWORK_KEY`). With `ephemeral: true` the
        device is removed by the control plane once it has been offline for 30 minutes
        (instead of being expired after 7 idle days) — for short-lived machines.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                siteId:
                  type: string
                  description: Defaults to the first site.
                ephemeral:
                  type: boolean
                  default: false
                  description: Enroll an ephemeral device.
            example: { siteId: "dev", ephemeral: true }
      responses:
        "200":
          description: The key and where to use it.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DeviceKey" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network/devices:
    get:
      tags: [Network]
      summary: My devices
      operationId: listMyDevices
      description: The caller's own enrolled devices on every site, read live from the control planes.
      responses:
        "200":
          description: The caller's devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices: { type: array, items: { $ref: "#/components/schemas/Device" } }
                  unreachable:
                    type: array
                    items: { type: string }
                    description: Site ids whose control plane did not answer — their devices are missing from `devices`.
                required: [devices, unreachable]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network/devices/{siteId}/{name}:
    delete:
      tags: [Network]
      summary: Remove one of my devices
      operationId: deleteMyDevice
      description: |
        Removes the caller's device(s) answering to `name` on that site — the device's name on the
        network or the hostname it enrolled with. Someone else's device reads as absent. Kicks the
        reconciler; writes an activity row.
      parameters:
        - { name: siteId, in: path, required: true, schema: { type: string } }
        - { name: name, in: path, required: true, schema: { type: string, pattern: "^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$" } }
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "404": { $ref: "#/components/responses/NotFound" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network/shares:
    get:
      tags: [Network]
      summary: My dev shares and what teammates share with me
      operationId: listDevShares
      description: |
        Dev shares: a user exposes ONE local port on their laptop to named users/groups on the same
        site for a bounded time. `mine` = shares the caller owns (with grantees); `sharedWithMe` = live
        shares the caller holds directly or through a group. Expired shares are never returned.
        Reachability is enforced by the ACL reconciler from the OWNER'S enrolled device IPs. Answers
        while the network exists even if `devShares` was later disabled (leftover shares stay visible).
      responses:
        "200":
          description: Both lists, soonest expiry first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mine: { type: array, items: { $ref: "#/components/schemas/DevShare" } }
                  sharedWithMe: { type: array, items: { $ref: "#/components/schemas/DevShareWithMe" } }
                required: [mine, sharedWithMe]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: [Network]
      summary: Start a dev share
      operationId: createDevShare
      description: |
        Writes a `share#<id>` grant per grantee (users and, when `allowGroupTargets`, groups) plus the
        share's definition, then kicks the ACL reconciler so the rule lands within seconds. `hostname`/`ip`
        are the desktop app's own tailnet address — display-only, so grantees get a URL; the rule itself
        targets the owner's enrolled device IPs. `hostname` must be the owner's node name on the share's
        site (`<name>.<siteId>.tail.internal`). A longer `durationHours` is clamped to
        `network.devShares.maxDurationHours`. With `device` (the name of one of the owner's devices on the
        site) the port opens on that device only — re-resolved by name on every reconciler pass, so a device
        that re-enrolls under the same name keeps its shares — and always to the owner's own other devices;
        `grantees` may then be empty and `hostname` defaults to `<device>.<siteId>.tail.internal`. At most
        `network.devShares.maxActiveSharesPerOwner` (default 10) live shares per owner, one per port per device (a share without `device` covers every device).
        501 while `devShares` is disabled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                port: { type: integer, minimum: 1, maximum: 65535 }
                label: { type: string, maxLength: 60, description: "Defaults to \"Port <port>\"." }
                siteId: { type: string, description: Defaults to the first site. }
                durationHours: { type: integer, minimum: 1 }
                hostname: { type: string, description: The owner's MagicDNS name. }
                ip: { type: string, description: The owner's tailnet IPv4 (100.64.0.0/10). }
                device: { type: string, description: "Bind the share to one of the owner's devices by name." }
                grantees:
                  type: array
                  description: At least one, unless `device` is set.
                  maxItems: 50
                  items:
                    type: object
                    properties:
                      kind: { type: string, enum: [user, group] }
                      id: { type: string }
                    required: [kind, id]
              required: [port, durationHours, grantees]
            example:
              port: 4200
              label: Checkout redesign
              siteId: dev
              durationHours: 8
              hostname: devs-macbook.dev.tail.internal
              grantees: [{ kind: user, id: 8d2c…-sub }, { kind: group, id: 1f4a…-group }]
      responses:
        "201":
          description: The new share as its owner sees it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  share: { $ref: "#/components/schemas/DevShare" }
                required: [share]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network/shares/directory:
    get:
      tags: [Network]
      summary: Who a dev share can target
      operationId: listDevShareDirectory
      description: |
        The one directory read open to non-admins, and deliberately thin: every user's sub + email
        (invited-but-unconfirmed users omitted) and every group's id, name and member count. 501 while
        `devShares` is disabled.
      responses:
        "200":
          description: Users and groups, sorted by email / name.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DevShareDirectory" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /network/shares/{shareId}:
    delete:
      tags: [Network]
      summary: Stop a dev share
      operationId: deleteDevShare
      description: |
        Owner or admin. Every grant row and the definition go; grantees who lose access get a revocation
        notice of kind `SHARE` (via `OWNER`, or `ADMIN` when an admin stopped it). Kicks the reconciler.
        Works while the network exists even if `devShares` was later disabled.
      parameters:
        - name: shareId
          in: path
          required: true
          schema: { type: string, pattern: "^[a-f0-9]{12}$" }
      responses:
        "204": { description: Stopped. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /resources:
    get:
      tags: [Resources]
      summary: My reachable resources
      operationId: listReachableResources
      description: Private-network resources the caller holds an active grant on — the only place connection details (`cidr`, `ports`, `dnsName`) are exposed to non-admins.
      responses:
        "200":
          description: Reachable resources, sorted by name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items: { $ref: "#/components/schemas/ReachableResource" }
                required: [resources]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /resources/expiry:
    get:
      tags: [Resources]
      summary: My resource expiry notices
      operationId: listResourceExpiryNotices
      responses:
        "200":
          description: Temporary resource grants nearing / past their end.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiring:
                    type: array
                    items: { $ref: "#/components/schemas/ResourceExpiryNotice" }
                  expired:
                    type: array
                    items: { $ref: "#/components/schemas/ResourceExpiryNotice" }
                required: [expiring, expired]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /resources/expiry/seen:
    post:
      tags: [Resources]
      summary: Acknowledge resource expiry notices
      operationId: markResourceExpiryNoticesSeen
      responses:
        "200":
          description: How many notices were newly marked seen.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Cleared" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /notifications/revocations:
    get:
      tags: [Notifications]
      summary: My revocation notices
      operationId: listRevocationNotices
      description: Access the caller lost (admin revoke, group change, reapproval, cascade), newest first. Kept 30 days.
      responses:
        "200":
          description: Revocation notices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  notices:
                    type: array
                    items: { $ref: "#/components/schemas/RevocationNotice" }
                required: [notices]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /notifications/revocations/seen:
    post:
      tags: [Notifications]
      summary: Acknowledge revocation notices
      operationId: markRevocationNoticesSeen
      responses:
        "200":
          description: How many notices were newly marked seen.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Cleared" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  # ---------------------------------------------------------------- admin ---

  /tokens/current:
    get:
      tags: [Tokens]
      summary: The token I am using
      operationId: currentToken
      description: |
        Who a personal access token acts as and what it may do. Any valid token may call this,
        whatever its scopes; a signed-in session gets a `400`.
      responses:
        "200":
          description: The token and its owner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokenId: { type: string }
                  name: { type: string }
                  scopes: { type: array, items: { $ref: "#/components/schemas/TokenScopeName" } }
                  roles: { type: array, items: { $ref: "#/components/schemas/TokenRole" } }
                  expiresAt: { type: string, format: date-time }
                  user:
                    type: object
                    properties:
                      userId: { type: string }
                      email: { type: string }
                    required: [userId]
                required: [tokenId, name, scopes, expiresAt, user]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /tokens:
    get:
      tags: [Tokens]
      summary: My personal access tokens
      operationId: listTokens
      description: The caller's tokens, newest first — expired ones until they drop out a week later. Never the secrets. Signed-in session only.
      responses:
        "200":
          description: The caller's tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens: { type: array, items: { $ref: "#/components/schemas/Token" } }
                required: [tokens]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: [Tokens]
      summary: Create a personal access token
      operationId: createToken
      description: |
        The secret is in this response and nowhere else — only its SHA-256 is stored. `expiresInDays` is
        required and capped by `personalAccessTokens.maxLifetimeDays` (default 90). `roles` limits an
        `aws`/`api` token to some of the roles the caller holds now (it never adds any). At most 25 active
        tokens per user. Signed-in session only; 501 while the feature is off.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, minLength: 1, maxLength: 60 }
                description: { type: string, maxLength: 200 }
                scopes: { type: array, minItems: 1, items: { $ref: "#/components/schemas/TokenScopeName" } }
                expiresInDays: { type: integer, minimum: 1 }
                roles: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/TokenRole" } }
              required: [name, scopes, expiresInDays]
            example: { name: "nightly report", scopes: ["aws"], expiresInDays: 30, roles: [{ accountNumber: "123456789012", roleName: "ReadOnly" }] }
      responses:
        "201":
          description: The token and its secret (shown once).
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { $ref: "#/components/schemas/Token" }
                  secret: { type: string, description: "`icpat_<tokenId>_<secret>` — the bearer token." }
                required: [token, secret]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "409": { $ref: "#/components/responses/Conflict" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /tokens/expiry:
    get:
      tags: [Tokens]
      summary: My token expiry notices
      operationId: listTokenExpiry
      description: The bell's two phases for the caller's tokens — expiring soon (the last day, or the second half of a shorter lifetime) and expired in the last 7 days. Signed-in session only.
      responses:
        "200":
          description: Both phases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiring: { type: array, items: { $ref: "#/components/schemas/TokenExpiryNotice" } }
                  expired: { type: array, items: { $ref: "#/components/schemas/TokenExpiryNotice" } }
                required: [expiring, expired]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "502": { $ref: "#/components/responses/Upstream" }

  /tokens/expiry/seen:
    post:
      tags: [Tokens]
      summary: Acknowledge my token expiry notices
      operationId: markTokenExpirySeen
      responses:
        "200":
          description: How many notices were acknowledged.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cleared: { type: integer }
                required: [cleared]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "502": { $ref: "#/components/responses/Upstream" }

  /tokens/{tokenId}:
    delete:
      tags: [Tokens]
      summary: Revoke one of my tokens
      operationId: revokeToken
      description: Takes effect on the token's next request. Someone else's token reads as absent. Signed-in session only.
      parameters:
        - { name: tokenId, in: path, required: true, schema: { type: string, pattern: "^[a-f0-9]{16}$" } }
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/TokenScope" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/setup:
    get:
      tags: ["Admin: setup"]
      summary: Setup checklist state
      operationId: getSetupStatus
      description: First-run checklist inputs, aggregated live — items check themselves off as the deployment fills in.
      responses:
        "200":
          description: Setup status.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SetupStatus" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/branding:
    put:
      tags: ["Admin: setup"]
      summary: Save the branding overlay
      operationId: saveBranding
      description: Writes `/branding.json` in the web bucket (the SPA fetches it from the web origin at boot — there is no GET here). `dismissed` hides the first-admin theme wizard.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one of `branding`, `dismissed`.
              properties:
                branding: { $ref: "#/components/schemas/BrandingOverlay" }
                dismissed: { type: boolean }
            example: { branding: { projectName: "Acme Access", primaryColor: "#3e63dd" }, dismissed: true }
      responses:
        "204": { description: Saved. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts:
    get:
      tags: ["Admin: accounts & roles"]
      summary: List the catalog
      operationId: adminListAccounts
      description: |
        Every registered account with its roles; each role carries its unexpired-grantee count.
        With `limit`, one page of the list contract: sorts `position` (the admin order, default), `name`, `number`; facets `environment`, `status`, `main` (`true`/`false`), plus `tenant`, `project`, `stage` on a deployment with account dimensions (`unclassified` for an account without one).
      parameters:
        - $ref: "#/components/parameters/listQ"
        - $ref: "#/components/parameters/listFilter"
        - $ref: "#/components/parameters/listSort"
        - $ref: "#/components/parameters/listLimit"
        - $ref: "#/components/parameters/listCursor"
      responses:
        "200":
          description: The catalog — the whole list, or one page when `limit` was passed.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items: { $ref: "#/components/schemas/AdminAccount" }
                    required: [accounts]
                  - $ref: "#/components/schemas/AdminAccountPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: accounts & roles"]
      summary: Register an account
      operationId: adminCreateAccount
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AccountCreate" }
            example: { accountNumber: "123456789012", name: "Production", environment: "prod", profileName: "acme-prod" }
      responses:
        "201":
          description: The account.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AccountEnvelope" }
        "200":
          description: Already registered with the same values (a retry); the stored account, nothing changed. Different values are a `409`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AccountEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/order:
    put:
      tags: ["Admin: accounts & roles"]
      summary: Set the display order of the accounts
      operationId: adminReorderAccounts
      description: The whole list, first to last; each account's position becomes its index, and each listed role's its position inside its account. This is the order every page shows to every user (Your access and the admin tabs). Accounts left out, and roles left out of an account's list, lose any position they had and list after the ordered ones, by name.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AccountOrder" }
            example: { accounts: [{ accountNumber: "111111111111", roles: ["DevRole", "AdminRole"] }, { accountNumber: "222222222222" }] }
      responses:
        "200":
          description: The ordered accounts as stored, in the new order — only the ones the request listed, never the whole catalog.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items: { $ref: "#/components/schemas/AdminAccount" }
                required: [accounts]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
  /admin/accounts/{accountNumber}:
    get:
      tags: ["Admin: accounts & roles"]
      summary: Get one account
      operationId: adminGetAccount
      parameters:
        - $ref: "#/components/parameters/accountNumber"
      responses:
        "200":
          description: The account with its roles.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AccountEnvelope" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    patch:
      tags: ["Admin: accounts & roles"]
      summary: Update an account
      operationId: adminUpdateAccount
      description: At least one field. `profileName` is the `~/.aws` profile users get when they hold exactly one role here; `""` clears it; it must be unique across accounts and roles (`409`).
      parameters:
        - $ref: "#/components/parameters/accountNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AccountPatch" }
            example: { name: "Production (EU)", status: "active" }
      responses:
        "200":
          description: The updated account.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AccountEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: accounts & roles"]
      summary: Remove an account
      operationId: adminDeleteAccount
      description: "**Cascades**: for each of the account's roles, every grant is revoked (losses are noticed), group bundles drop it and its open requests are denied with the reason; then the roles and the account go. Refused with 409 while the account still has network resources — remove those first. Grants go before the catalog rows, so a call that failed halfway can be repeated."
      parameters:
        - $ref: "#/components/parameters/accountNumber"
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/{accountNumber}/roles:
    post:
      tags: ["Admin: accounts & roles"]
      summary: Add a role
      operationId: adminCreateRole
      description: Registers a role users can be granted. Auto-registers the account if it is not catalogued yet. The ARN's account must equal the path's `accountNumber`.
      parameters:
        - $ref: "#/components/parameters/accountNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RoleCreate" }
            example: { roleName: "ReadOnly", displayName: "Read only", roleArn: "arn:aws:iam::123456789012:role/ReadOnly", policyTier: "READ_ONLY", sessionDurationSeconds: 3600, icon: "view" }
      responses:
        "201":
          description: The role.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RoleEnvelope" }
        "200":
          description: Already registered with the same values (a retry); the stored role, nothing changed. Different values, or a name that differs only in case, are a `409`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RoleEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/{accountNumber}/roles/{roleName}:
    patch:
      tags: ["Admin: accounts & roles"]
      summary: Update a role
      operationId: adminUpdateRole
      description: At least one field. `sessionDurationSeconds` (900–43200) is what vends ask STS for; `profileName` must be unique across accounts and roles (`409`).
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RolePatch" }
            example: { displayName: "Read only (EU)", sessionDurationSeconds: 7200, color: "#3e63dd" }
      responses:
        "200":
          description: The updated role.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RoleEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: accounts & roles"]
      summary: Remove a role
      operationId: adminDeleteRole
      description: "**Cascades**: every grant on the role is revoked (losses are noticed), groups bundling it drop it (a group left empty is removed), and its open requests and reviews are denied with the reason. Grants go before the catalog row, so a call that failed halfway can be repeated: an already-removed role still sweeps its leftovers before the 404."
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/{accountNumber}/roles/{roleName}/test-session:
    post:
      tags: ["Admin: accounts & roles"]
      summary: Test a session length
      operationId: adminTestSession
      description: "Tries `AssumeRoleWithWebIdentity` as the calling admin for `durationSeconds`, discarding the credentials. `ok: false` carries STS's message (usually the IAM role's MaxSessionDuration is lower)."
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                durationSeconds: { type: integer, minimum: 900, maximum: 43200 }
              required: [durationSeconds]
            example: { durationSeconds: 14400 }
      responses:
        "200":
          description: The outcome.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TestSessionResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/{accountNumber}/roles/{roleName}/grants:
    get:
      tags: ["Admin: grants"]
      summary: Who holds this role
      operationId: adminListGrantees
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      responses:
        "200":
          description: Holders, direct and via groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grantees:
                    type: array
                    items: { $ref: "#/components/schemas/Grantee" }
                required: [grantees]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/accounts/{accountNumber}/roles/{roleName}/grants/{userId}:
    put:
      tags: ["Admin: grants"]
      summary: Grant a role
      operationId: adminAssignRole
      description: Idempotent. `durationHours` makes the grant temporary; re-granting overwrites the expiry (the "extend" path). A long-term grant is never downgraded to temporary. `userId` may be a service user's client id.
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
        - $ref: "#/components/parameters/userId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                durationHours: { $ref: "#/components/schemas/DurationHours" }
            example: { durationHours: 24 }
      responses:
        "200":
          description: The grant as stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grant: { $ref: "#/components/schemas/Grant" }
                required: [grant]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: grants"]
      summary: Revoke a role
      operationId: adminRevokeRole
      description: Removes the direct grant only — group-provided access stays (change the group instead). The loss is noticed if it ends the user's access.
      parameters:
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
        - $ref: "#/components/parameters/userId"
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/grants/bulk:
    post:
      tags: ["Admin: grants"]
      summary: Grant roles in bulk
      operationId: adminBulkAssign
      description: Up to 20 roles × 50 users in one call. Always `200` with a per-pair result — one bad pair never fails the rest.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userIds: { type: array, items: { type: string }, minItems: 1, maxItems: 50 }
                roles: { type: array, items: { $ref: "#/components/schemas/RoleRef" }, minItems: 1, maxItems: 20 }
                durationHours: { $ref: "#/components/schemas/DurationHours" }
              required: [userIds, roles]
            example: { userIds: ["1a2b3c4d-0000-4000-8000-000000000000"], roles: [{ accountNumber: "123456789012", roleName: "ReadOnly" }], durationHours: 168 }
      responses:
        "200":
          description: Per-pair results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items: { $ref: "#/components/schemas/BulkAssignResult" }
                required: [results]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/grants/bulk-revoke:
    post:
      tags: ["Admin: grants"]
      summary: Revoke roles in bulk
      operationId: adminBulkRevoke
      description: Always `200` with per-pair results — pairs with no direct grant are `SKIPPED`; group-provided pairs `FAILED` (membership, not a direct revoke, removes those).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userIds: { type: array, items: { type: string }, minItems: 1, maxItems: 50 }
                roles: { type: array, items: { $ref: "#/components/schemas/RoleRef" }, minItems: 1, maxItems: 20 }
              required: [userIds, roles]
            example: { userIds: ["1a2b3c4d-0000-4000-8000-000000000000"], roles: [{ accountNumber: "123456789012", roleName: "ReadOnly" }] }
      responses:
        "200":
          description: Per-pair results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items: { $ref: "#/components/schemas/BulkRevokeResult" }
                required: [results]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users:
    get:
      tags: ["Admin: users"]
      summary: List users
      operationId: adminListUsers
      description: |
        The Cognito directory (source of truth — a user with no grants still appears) with each user's effective roles and resources.
        With `limit`, one page of the list contract: sorts `email` (default), `lastSeen`; facets `admin` (`admin`/`member`), `status` (`invited`/`active`).
      parameters:
        - $ref: "#/components/parameters/listQ"
        - $ref: "#/components/parameters/listFilter"
        - $ref: "#/components/parameters/listSort"
        - $ref: "#/components/parameters/listLimit"
        - $ref: "#/components/parameters/listCursor"
      responses:
        "200":
          description: Users — the whole list, or one page when `limit` was passed.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      users:
                        type: array
                        items: { $ref: "#/components/schemas/User" }
                    required: [users]
                  - $ref: "#/components/schemas/UserPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: users"]
      summary: Invite a user
      operationId: adminCreateUser
      description: Creates the Cognito user and, unless `sendEmail` is `false`, **sends the invitation email**. The response carries the sign-up link either way — the same `/login#inv=…` link the email holds, valid 7 days; anyone holding it can set the password. `409` if the email is taken.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                admin: { type: boolean, default: false, description: Also add to the `admins` group. }
                sendEmail: { type: boolean, default: true, description: "`false`: Cognito emails nothing and the response carries `signupLink` for you to pass on." }
              required: [email]
            example: { email: "new.user@example.com", admin: false, sendEmail: true }
      responses:
        "201":
          description: "The new user (`pendingInvite: true`), plus `signupLink` only when `sendEmail` was `false`."
          content:
            application/json:
              schema:
                type: object
                properties:
                  user: { $ref: "#/components/schemas/User" }
                  signupLink: { type: string, description: "Only when `sendEmail` was `false` — it carries the temporary password. Absolute when the deploy has a web domain, else path-only (`/login#inv=…`)." }
                required: [user]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/bulk:
    post:
      tags: ["Admin: users"]
      summary: Invite users in bulk
      operationId: adminBulkCreateUsers
      description: Up to 50 emails. Always `200` with a per-row `CREATED`/`FAILED` result — one taken email never fails the rest. Each `CREATED` row sent a real invitation email, or — with `sendEmail` `false` — carries its `signupLink` instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails: { type: array, items: { type: string, format: email }, minItems: 1, maxItems: 50 }
                admin: { type: boolean, default: false }
                sendEmail: { type: boolean, default: true }
              required: [emails]
            example: { emails: ["a@example.com", "b@example.com"], admin: false }
      responses:
        "200":
          description: Per-row results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items: { $ref: "#/components/schemas/BulkCreateResult" }
                required: [results]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/bulk-delete:
    post:
      tags: ["Admin: users"]
      summary: Delete users in bulk
      operationId: adminBulkDeleteUsers
      description: Up to 50 users, each with the full delete cascade. Always `200` with per-row results; the caller's own account is refused so a sweep can never lock everyone out.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userIds: { type: array, items: { type: string }, minItems: 1, maxItems: 50 }
              required: [userIds]
            example: { userIds: ["1a2b3c4d-0000-4000-8000-000000000000"] }
      responses:
        "200":
          description: Per-row results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items: { $ref: "#/components/schemas/BulkDeleteResult" }
                required: [results]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}:
    get:
      tags: ["Admin: users"]
      summary: One user with all their access
      operationId: adminGetUser
      description: The listing caps each user's `roles` and `resources` at 50 entries (`roleCount` / `resourceCount` carry the totals); this returns every entry for one user.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: The user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user: { $ref: "#/components/schemas/User" }
                required: [user]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    patch:
      tags: ["Admin: users"]
      summary: Update a user
      operationId: adminUpdateUser
      description: Change the email and/or `admins`-group membership. Removing the last admin is refused (`409`).
      parameters:
        - $ref: "#/components/parameters/userId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one field.
              properties:
                email: { type: string, format: email }
                admin: { type: boolean }
            example: { admin: true }
      responses:
        "204": { description: Updated. }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: users"]
      summary: Delete a user
      operationId: adminDeleteUser
      description: "**Cascades**: grants, group memberships, preferences and access requests go too."
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/grants:
    get:
      tags: ["Admin: users"]
      summary: A user's role grants
      operationId: adminListUserGrants
      description: Everything the user holds, direct and via groups (audit view). Works for service users too.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: Grants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grants:
                    type: array
                    items: { $ref: "#/components/schemas/UserGrant" }
                required: [grants]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/resource-grants:
    get:
      tags: ["Admin: users"]
      summary: A user's resource grants
      operationId: adminListUserResourceGrants
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: Resource grants with resolved names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grants:
                    type: array
                    items: { $ref: "#/components/schemas/UserResourceGrantNamed" }
                required: [grants]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/revoke-all:
    post:
      tags: ["Admin: users"]
      summary: Revoke everything
      operationId: adminRevokeAll
      description: Every direct role and resource grant AND every group membership of the user goes (preferences stay). Each real loss is noticed.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: How many rows were removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed: { type: integer }
                required: [removed]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/resend-invite:
    post:
      tags: ["Admin: users"]
      summary: Resend the invitation
      operationId: adminResendInvite
      description: Re-sends the invitation email with a fresh temporary password. `409` if the user already completed setup.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "204": { description: Sent. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/signup-link:
    post:
      tags: ["Admin: users"]
      summary: Mint a fresh sign-up link
      operationId: adminMintSignupLink
      description: A new temporary password for a user who has not set their own yet, returned as the `/login#inv=…` link (valid 7 days). It retires the previous temporary password — the emailed link and any copied one stop working. `409` once the user completed setup.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: The link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signupLink: { type: string }
                required: [signupLink]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/reset-mfa:
    post:
      tags: ["Admin: users"]
      summary: Reset MFA
      operationId: adminResetMfa
      description: Lost-authenticator recovery — TOTP off, the user signs in with password alone again and can re-enrol. No-op if never enrolled.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "204": { description: Reset. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/tokens:
    get:
      tags: ["Admin: tokens"]
      summary: Every user's personal access tokens
      operationId: adminListTokens
      description: Newest first, with the owner. Never the secrets. Signed-in admin session only.
      responses:
        "200":
          description: All tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens: { type: array, items: { $ref: "#/components/schemas/AdminToken" } }
                required: [tokens]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/tokens/{tokenId}:
    delete:
      tags: ["Admin: tokens"]
      summary: Revoke anyone's token
      operationId: adminRevokeToken
      parameters:
        - { name: tokenId, in: path, required: true, schema: { type: string, pattern: "^[a-f0-9]{16}$" } }
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/service-users:
    get:
      tags: ["Admin: service users"]
      summary: List service users
      operationId: adminListServiceUsers
      responses:
        "200":
          description: Service users with their role grants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  serviceUsers:
                    type: array
                    items: { $ref: "#/components/schemas/ServiceUser" }
                required: [serviceUsers]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: service users"]
      summary: Create a service user
      operationId: adminCreateServiceUser
      description: 'Creates a `client_credentials` app client with the given scopes. The `201` body carries the `clientSecret` — **the only time it is ever returned**. Grant roles and resources to it with the ordinary grant routes, using its `clientId` as the `userId`. Needs `admin.write.all` (or a human admin).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, minLength: 1, maxLength: 64, description: Unique among live service users. }
                scopes: { type: array, minItems: 1, items: { $ref: "#/components/schemas/ServiceUserScopeName" }, description: "What its tokens may call; `admin.write.all` = every `/admin` route, `admin.read.all` their reads." }
              required: [name, scopes]
            example: { name: "vm-provisioner", scopes: ["aws", "network"] }
      responses:
        "201":
          description: The service user and its secret.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ServiceUserWithSecret" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/service-users/{clientId}:
    delete:
      tags: ["Admin: service users"]
      summary: Delete a service user
      operationId: adminDeleteServiceUser
      description: "**Cascades**: the app client(s), every grant, and the registry row. Issued tokens stay signature-valid up to an hour but are refused on the next request."
      parameters:
        - $ref: "#/components/parameters/clientId"
      responses:
        "204": { description: Deleted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/service-users/{clientId}/scopes:
    put:
      tags: ["Admin: service users"]
      summary: Replace the scopes
      operationId: adminUpdateServiceUserScopes
      description: "Replaces the scope set. The registry row is read on every request, so a narrowing holds from the service user's next call — tokens already issued do not keep what they had. Mid-rotation the still-working previous client gets the same set."
      parameters:
        - $ref: "#/components/parameters/clientId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scopes: { type: array, minItems: 1, items: { $ref: "#/components/schemas/ServiceUserScopeName" } }
              required: [scopes]
            example: { scopes: ["aws", "network"] }
      responses:
        "200":
          description: The service user with its new scopes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  serviceUser: { $ref: "#/components/schemas/ServiceUser" }
                required: [serviceUser]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/service-users/{clientId}/rotate:
    post:
      tags: ["Admin: service users"]
      summary: Rotate the secret
      operationId: adminRotateServiceUser
      description: Creates a replacement client + secret carrying the same grants and scopes; the previous secret keeps working until `DELETE …/previous`. `409` while a previous secret is still active. The returned `serviceUser.clientId` is the NEW id.
      parameters:
        - $ref: "#/components/parameters/clientId"
      responses:
        "200":
          description: The replacement and its secret (returned once).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ServiceUserWithSecret" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/service-users/{clientId}/previous:
    delete:
      tags: ["Admin: service users"]
      summary: Finish a rotation
      operationId: adminRemovePreviousSecret
      description: Retires the previous client (its grants and registry row go). `clientId` is the CURRENT client's id.
      parameters:
        - $ref: "#/components/parameters/clientId"
      responses:
        "204": { description: Retired. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups:
    get:
      tags: ["Admin: groups"]
      summary: List groups
      operationId: adminListGroups
      description: Every bundle with its roles, resources (names resolved) and members (emails resolved).
      responses:
        "200":
          description: Groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items: { $ref: "#/components/schemas/GroupView" }
                required: [groups]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: groups"]
      summary: Create a group
      operationId: adminCreateGroup
      description: A bundle needs at least one role or resource. Names are unique (case-insensitive, `409`).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GroupInput" }
            example: { name: "Platform team", description: "Read access everywhere", roles: [{ accountNumber: "123456789012", roleName: "ReadOnly" }], resources: [] }
      responses:
        "201":
          description: The group (members and resources as raw ids).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}:
    get:
      tags: ["Admin: groups"]
      summary: One group with its whole bundle
      operationId: adminGetGroup
      description: The list caps each group's `roles` at 50 (`roleCount` carries the total); this returns every role, member and resource of one group.
      parameters:
        - $ref: "#/components/parameters/groupId"
      responses:
        "200":
          description: The group.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupEnvelope" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    patch:
      tags: ["Admin: groups"]
      summary: Update a group
      operationId: adminUpdateGroup
      description: At least one field. A `roles`/`resources` change reconciles every member — added targets are granted to all, removed ones revoked unless held directly or via another group (losses are noticed).
      parameters:
        - $ref: "#/components/parameters/groupId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GroupInput" }
            example: { roles: [{ accountNumber: "123456789012", roleName: "ReadOnly" }, { accountNumber: "123456789012", roleName: "PowerUser" }] }
      responses:
        "200":
          description: The updated group.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: groups"]
      summary: Delete a group
      operationId: adminDeleteGroup
      description: Pulls the bundle from every member (direct and other-group access survives; losses are noticed).
      parameters:
        - $ref: "#/components/parameters/groupId"
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/roles:
    get:
      tags: ["Admin: groups"]
      summary: The bundle's roles, paged
      operationId: adminListGroupRoles
      description: The list contract over one group's roles (`q` matches role name, display name, account name or number; sorts `account` (default), `role`). Without `limit`, the first 50.
      parameters:
        - $ref: "#/components/parameters/groupId"
        - $ref: "#/components/parameters/listQ"
        - $ref: "#/components/parameters/listSort"
        - $ref: "#/components/parameters/listLimit"
        - $ref: "#/components/parameters/listCursor"
      responses:
        "200":
          description: One page of the bundle.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListPage"
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            accountNumber: { $ref: "#/components/schemas/AccountNumber" }
                            accountName: { type: string }
                            roleName: { type: string }
                            displayName: { type: string }
                          required: [accountNumber, roleName]
                    required: [items]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: groups"]
      summary: Add one role to a group
      operationId: adminAddGroupRole
      description: |
        Adds a single catalogued role to the bundle — the call an account-registration pipeline makes per new account.
        Idempotent and race-free: the row is written only if absent, so a retry or two concurrent adds leave one row,
        and a role already in the bundle answers `200` with nothing changed, noticed or logged. Members who gain the
        role are noticed, as with a `PATCH`. Prefer this over `PATCH` with the full role list for large groups.
        Answers with the change, not the bundle (a 4,000-role group answers in well under a second); read the bundle
        with `GET /admin/groups/{groupId}` or page it with `GET …/roles`.
      parameters:
        - $ref: "#/components/parameters/groupId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GroupRoleRef" }
            example: { accountNumber: "123456789012", roleName: "ReadOnly" }
      responses:
        "201":
          description: The role was added.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupRoleChange" }
        "200":
          description: The role was already in the bundle; nothing changed.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupRoleChange" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/roles/bulk:
    post:
      tags: ["Admin: groups"]
      summary: Add every matching account's role to a group
      operationId: adminAddGroupRolesBulk
      description: |
        The group editor's "add by dimension": every registered account matching `filter` (dimension values, `unclassified` for
        accounts without one; keys AND together, values OR) and `q` (account name or number) that has a role named `roleName`
        goes into the bundle. Rows are written only if absent, roles already bundled are skipped, members who gain
        access are noticed as with a single add. One call writes at most 500 new rows and reports `remaining`; call again
        until it is 0. `dryRun: true` only counts. Matching is over the catalog; access is unchanged by it until the rows
        are written.
      parameters:
        - $ref: "#/components/parameters/groupId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roleName: { type: string, minLength: 1 }
                filter:
                  type: object
                  properties:
                    tenant: { type: array, items: { type: string } }
                    project: { type: array, items: { type: string } }
                    stage: { type: array, items: { type: string } }
                q: { type: string, description: Narrows by account name or number (every whitespace-separated token must occur). }
                dryRun: { type: boolean, default: false }
              required: [roleName]
            example: { roleName: "ReadOnly", filter: { tenant: ["acme"], stage: ["prod"] } }
      responses:
        "201":
          description: At least one role was added.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupRolesBulkResult" }
        "200":
          description: Nothing new (every match was already bundled), or the dry run's count.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GroupRolesBulkResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/suggest:
    get:
      tags: ["Admin: groups"]
      summary: Groups to add a freshly registered role to
      operationId: adminSuggestGroups
      description: |
        Groups that already bundle a role of this name in the account's sibling accounts — same tenant and stage by the
        catalog's dimensions (deployments with `accountDimensions`). The role form offers them right after a role is
        registered; adding is the single-role `POST /admin/groups/{groupId}/roles`. Empty without dimensions or siblings;
        at most 10, most siblings first.
      parameters:
        - name: accountNumber
          in: query
          required: true
          schema: { $ref: "#/components/schemas/AccountNumber" }
        - name: roleName
          in: query
          required: true
          schema: { type: string, minLength: 1 }
      responses:
        "200":
          description: Suggested groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  suggestions:
                    type: array
                    items:
                      type: object
                      properties:
                        groupId: { type: string }
                        name: { type: string }
                        siblingAccounts: { type: integer, minimum: 1, description: Sibling accounts whose role of this name the group bundles. }
                      required: [groupId, name, siblingAccounts]
                required: [suggestions]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/roles/{accountNumber}/{roleName}:
    delete:
      tags: ["Admin: groups"]
      summary: Remove one role from a group
      operationId: adminRemoveGroupRole
      description: Removes a single role from the bundle (members lose it unless held another way, and are noticed). A role not in the bundle is still `204`. The bundle's last target cannot be removed this way (`400`) — delete the group instead.
      parameters:
        - $ref: "#/components/parameters/groupId"
        - $ref: "#/components/parameters/accountNumber"
        - $ref: "#/components/parameters/roleName"
      responses:
        "204": { description: Removed, or was not there. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/members:
    post:
      tags: ["Admin: groups"]
      summary: Add members
      operationId: adminAddMembers
      description: Every new member inherits the whole bundle. Already-members are ignored.
      parameters:
        - $ref: "#/components/parameters/groupId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UserIdList" }
            example: { userIds: ["1a2b3c4d-0000-4000-8000-000000000000"] }
      responses:
        "200":
          description: How many members were added.
          content:
            application/json:
              schema:
                type: object
                properties:
                  added: { type: integer }
                required: [added]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/members/remove:
    post:
      tags: ["Admin: groups"]
      summary: Remove members
      operationId: adminRemoveMembers
      description: A POST because it carries a body. Only this group's access is pulled (losses are noticed).
      parameters:
        - $ref: "#/components/parameters/groupId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UserIdList" }
            example: { userIds: ["1a2b3c4d-0000-4000-8000-000000000000"] }
      responses:
        "200":
          description: How many members were removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed: { type: integer }
                required: [removed]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/requests:
    get:
      tags: ["Admin: requests"]
      summary: Queue or history
      operationId: adminListRequests
      description: With `status`, that queue (oldest first); without it, the full history (newest first). Rows carry the requester's email, service-user name, group name and resource name where applicable.
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [PENDING, APPROVED, DENIED] }
          example: PENDING
        - name: usage
          in: query
          description: "`1` adds `usage` (the holder's role use in the review window) to pending reapprovals. Costly — only the Requests page sets it, never the bell poll."
          schema: { type: string, enum: ["1"] }
      responses:
        "200":
          description: Requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requests:
                    type: array
                    items: { $ref: "#/components/schemas/AccessRequestAdminView" }
                required: [requests]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/requests/{requestId}/approve:
    post:
      tags: ["Admin: requests"]
      summary: Approve
      operationId: adminApproveRequest
      description: Approves **and grants** (a role, a resource, or — for reviews — confirms the admin/service user/group). The approver's `durationHours` is final, overriding what was requested. `409` if another admin already decided.
      parameters:
        - $ref: "#/components/parameters/requestId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                note: { type: string, maxLength: 500, description: Shown to the requester with the decision. }
                durationHours: { $ref: "#/components/schemas/DurationHours" }
            example: { note: "Approved for the incident.", durationHours: 24 }
      responses:
        "200":
          description: The decided request.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RequestEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/requests/{requestId}/deny:
    post:
      tags: ["Admin: requests"]
      summary: Deny
      operationId: adminDenyRequest
      description: Grants nothing. For a reapproval/review, denying **ends** the standing access under review (losses are noticed). `409` if already decided.
      parameters:
        - $ref: "#/components/parameters/requestId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                note: { type: string, maxLength: 500 }
            example: { note: "Not needed for this role." }
      responses:
        "200":
          description: The decided request.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RequestEnvelope" }
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/resources:
    get:
      tags: ["Admin: resources"]
      summary: List resources
      operationId: adminListResources
      description: The private-network resource catalog with connection details.
      responses:
        "200":
          description: Resources, sorted by name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items: { $ref: "#/components/schemas/Resource" }
                required: [resources]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }
    post:
      tags: ["Admin: resources"]
      summary: Register a resource
      operationId: adminCreateResource
      description: A resource is reachable only through a site, so this is `501` on deployments without a private network. `cidr` accepts a bare IP or a /16–/32 CIDR. The account must be catalogued (`404`).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ResourceCreate" }
            example: { accountNumber: "123456789012", name: "Staging database", type: DATABASE, cidr: "10.0.1.25/32", ports: [5432], dnsName: "staging-db.internal", securityGroupId: "sg-0123456789abcdef0", description: "Postgres 16" }
      responses:
        "201":
          description: The resource.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/resources/status:
    get:
      tags: ["Admin: network"]
      summary: Reconciler status
      operationId: adminReconcilerStatus
      description: The grants→ACL reconciler's last-pass summary — per-resource reachability verdicts, connector freshness, rule counts.
      responses:
        "200":
          description: Status.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ReconcilerStatus" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/resources/{resourceId}:
    patch:
      tags: ["Admin: resources"]
      summary: Update a resource
      operationId: adminUpdateResource
      description: At least one field. `accountNumber` is immutable (it IS the connector binding) — moving a resource means recreating it.
      parameters:
        - $ref: "#/components/parameters/resourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ResourcePatch" }
            example: { ports: [5432, 5433], description: "Postgres 16 + pgbouncer" }
      responses:
        "200":
          description: The updated resource.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceEnvelope" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: resources"]
      summary: Remove a resource
      operationId: adminDeleteResource
      description: "**Cascades**: every grant on the resource is revoked (losses are noticed), groups bundling it drop it (a group left empty is removed), and its open requests and reviews are denied with the reason. Grants go before the catalog row, so a call that failed halfway can be repeated."
      parameters:
        - $ref: "#/components/parameters/resourceId"
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/resources/{resourceId}/grants:
    get:
      tags: ["Admin: resources"]
      summary: Who can reach this resource
      operationId: adminListResourceGrantees
      parameters:
        - $ref: "#/components/parameters/resourceId"
      responses:
        "200":
          description: Holders with emails resolved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grantees:
                    type: array
                    items: { $ref: "#/components/schemas/ResourceGrantee" }
                required: [grantees]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/resources/{resourceId}/grants/{userId}:
    put:
      tags: ["Admin: resources"]
      summary: Grant a resource
      operationId: adminAssignResource
      description: Idempotent; re-granting overwrites the expiry. A long-term grant is never downgraded. Reachability follows on the reconciler's next pass (≤ 5 min).
      parameters:
        - $ref: "#/components/parameters/resourceId"
        - $ref: "#/components/parameters/userId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                durationHours: { $ref: "#/components/schemas/DurationHours" }
            example: { durationHours: 72 }
      responses:
        "200":
          description: The grant.
          content:
            application/json:
              schema:
                type: object
                properties:
                  grant: { $ref: "#/components/schemas/UserResourceGrant" }
                required: [grant]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: resources"]
      summary: Revoke a resource
      operationId: adminRevokeResource
      parameters:
        - $ref: "#/components/parameters/resourceId"
        - $ref: "#/components/parameters/userId"
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/network:
    get:
      tags: ["Admin: network"]
      summary: Network topology
      operationId: adminNetworkTopology
      description: Everything the admin Network map needs — the full site config (split DNS and declared VPCs included) plus the reconciler's last-pass status.
      responses:
        "200":
          description: Sites and status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sites:
                    type: array
                    items: { $ref: "#/components/schemas/NetworkSite" }
                  status: { $ref: "#/components/schemas/ReconcilerStatus" }
                required: [sites, status]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/network/shares:
    get:
      tags: ["Admin: network"]
      summary: Every live dev share
      operationId: adminListDevShares
      description: Owner, port, site, expiry and grantees of every unexpired share; stop one with `DELETE /network/shares/{shareId}` (admins may).
      responses:
        "200":
          description: Soonest expiry first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  shares: { type: array, items: { $ref: "#/components/schemas/DevShare" } }
                required: [shares]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/network/sync:
    post:
      tags: ["Admin: network"]
      summary: Sync now
      operationId: adminNetworkSync
      description: Kicks the grants→ACL reconciler ahead of its 5-minute schedule. Fire-and-forget — re-read `GET /admin/resources/status` for the outcome.
      responses:
        "202":
          description: Sync requested.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Message" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "501": { $ref: "#/components/responses/NotDeployed" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/audit:
    get:
      tags: ["Admin: audit"]
      summary: The activity log
      operationId: adminListAudit
      description: |
        Every recorded action, newest first: who did it, what, to whom or what, the outcome and why. The window is
        `from`/`to` (a span of at most 90 days, anywhere inside the retention), or `days` back from now (default 7).
        A full page (`limit`, default 200, max 1000) reports `nextBefore`; pass it back as `before` for older rows.
        `user` (the person, group or service user an action was about) returns that subject's own trail. Per-user
        derived rows (`derived: true`, written by the access diff for group, cascade and bulk changes) are hidden
        unless `derived=true`. Names are joined from the directory,
        the group list and the resource catalog; a caller deleted since carries `deleted: true` and their snapshot name.
        Rows written before the general log (vend-only) are returned in the same shape.
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date-time }
        - name: to
          in: query
          schema: { type: string, format: date-time }
        - name: before
          in: query
          description: Upper bound for the next page, inclusive (the previous page's `nextBefore`); send `skip` with it.
          schema: { type: string, format: date-time }
        - name: skip
          in: query
          description: Comma-separated event ids already held whose `at` equals `before` — rows written in one batch can share an instant, so the cursor is inclusive and these are left out.
          schema: { type: string }
        - name: days
          in: query
          description: Shorthand for `from` = now minus this many days.
          schema: { type: integer, minimum: 1, maximum: 90 }
          example: 7
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 1000, default: 200 }
        - name: user
          in: query
          description: Subject ids, comma-separated (Cognito subs, group ids or service-user client ids; at most 10 — one indexed query each, merged). `userId` is accepted as an alias.
          schema: { type: string }
        - name: userId
          in: query
          deprecated: true
          schema: { type: string }
        - name: actor
          in: query
          description: Who did it, comma-separated (subs, client ids, or `system:<job>`; at most 10). Rows from before the general log are found by their caller; VPN session rows (`vpn.connect`/`vpn.disconnect`) by the person who connected, never by `system:reconciler`.
          schema: { type: string }
        - name: category
          in: query
          description: Comma-separated.
          schema: { type: string, example: "access,request" }
        - name: outcome
          in: query
          description: Comma-separated.
          schema: { type: string, example: "DENIED,FAILED" }
        - name: account
          in: query
          description: Comma-separated account numbers.
          schema: { type: string }
        - name: group
          in: query
          description: "Comma-separated group ids — everything about each group: its own rows, rows through it, rows where it is the subject."
          schema: { type: string }
        - name: target
          in: query
          description: Exact targets (`role#<account>#<name>`, `resource#<id>`, …). Repeat the parameter for several; a value is never split (a role name may contain a comma).
          schema:
            type: array
            items: { type: string }
          style: form
          explode: true
        - name: derived
          in: query
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: One page of the log.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ActivityPage" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/access-report/jobs:
    post:
      tags: ["Admin: audit"]
      summary: Build the access report in the background
      operationId: adminStartAccessReport
      description: Starts the report as a job (a large catalog produces more rows than one API call may carry) and answers at once with its id. Poll `GET /admin/access-report/jobs/{jobId}` until `status` is `done`, then download from `url` (valid 15 minutes). Only the admin who started a job can read it.
      responses:
        "202":
          description: The job, running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job: { $ref: "#/components/schemas/ReportJob" }
                required: [job]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/access-report/jobs/{jobId}:
    get:
      tags: ["Admin: audit"]
      summary: An access report job
      operationId: adminGetAccessReportJob
      parameters:
        - name: jobId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: The job; with `url` once done.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job: { $ref: "#/components/schemas/ReportJob" }
                required: [job]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/access-report:
    get:
      tags: ["Admin: audit"]
      summary: Who can reach what right now (CSV)
      operationId: adminAccessReport
      description: One row per person (or service user) and target they hold this instant — how (direct, or through which groups), who granted it, when, until when, and when they were last seen. The log explains how each row came to be; this is the state. Built inline, so it fits only while the result stays under API Gateway's 6 MB; the app uses the job endpoints above.
      responses:
        "200":
          description: "A CSV download (`Content-Disposition: attachment`), UTF-8 with BOM."
          content:
            text/csv:
              schema: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /plugins:
    get:
      tags: [Plugins]
      summary: Plugins this caller may open
      operationId: listPlugins
      description: >-
        Metadata only, never plugin code. A plugin appears only where the caller has an available capability,
        and a UI entry only where its own permission is available in at least one listed account. Account names
        come from the Accounts catalog, so a caller holding nothing but a plugin grant still sees the account.
        The feature being off, or no plugin being registered, is an empty list — never an error, and never
        cached across callers.
      responses:
        "200":
          description: The caller's plugins.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PluginDiscovery" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /plugins/expiry:
    get:
      tags: [Plugins]
      summary: My plugin expiry notices
      operationId: listPluginExpiryNotices
      description: Temporary plugin permissions nearing / past their end, named for the bell (a removed plugin keeps its label; an account without a name shows its number).
      responses:
        "200":
          description: Soonest expiry first; most recently expired first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiring:
                    type: array
                    items: { $ref: "#/components/schemas/PluginExpiryNotice" }
                  expired:
                    type: array
                    items: { $ref: "#/components/schemas/PluginExpiryNotice" }
                required: [expiring, expired]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /plugins/expiry/seen:
    post:
      tags: [Plugins]
      summary: Acknowledge plugin expiry notices
      operationId: markPluginExpiryNoticesSeen
      responses:
        "200":
          description: How many notices were newly marked seen.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Cleared" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/plugins:
    get:
      tags: ["Admin: plugins"]
      summary: Every plugin definition
      operationId: adminListPlugins
      description: >-
        The grant editor's view: installed, disabled and unavailable definitions, plus tombstones still worth
        labelling for grants that outlived them. Independent of the admin's own plugin grants, so a binding
        nobody holds yet is still assignable. Handler internals and credentials are never included.
      responses:
        "200":
          description: The catalog.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PluginAdminCatalog" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/users/{userId}/plugin-grants:
    get:
      tags: ["Admin: plugins"]
      summary: A user's plugin access
      operationId: adminListUserPluginGrants
      description: >-
        Their stored plugin rows (expired and dormant included, so the editor can show why one does nothing)
        and the capabilities those add up to, direct and through groups. A sibling of the resource-grants
        view: one call covers every plugin, so the user page never sweeps per-plugin endpoints.
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: Stored assignments and effective capabilities.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserPluginAccess" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/groups/{groupId}/plugin-grants:
    get:
      tags: ["Admin: plugins"]
      summary: A group's plugin assignments
      operationId: adminListGroupPluginGrants
      description: >-
        The bindings this group hands its members, each marked with whether it can authorize anything right
        now. The groups list carries the same bindings as bare references; this adds the availability the
        editor needs to show a dormant assignment as dormant and still offer to revoke it.
      parameters:
        - $ref: "#/components/parameters/groupId"
      responses:
        "200":
          description: The group's assignments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignments:
                    type: array
                    items: { $ref: "#/components/schemas/PluginAssignment" }
                required: [assignments]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }

  /admin/plugins/{pluginId}/accounts/{accountNumber}/grants:
    get:
      tags: ["Admin: plugins"]
      summary: Who holds this plugin binding
      operationId: adminListPluginGrants
      description: Stored assignments (users and groups, expired rows included) and the effective holders with provenance.
      parameters:
        - $ref: "#/components/parameters/pluginId"
        - $ref: "#/components/parameters/accountNumber"
      responses:
        "200":
          description: Assignments and holders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignments:
                    type: array
                    items: { $ref: "#/components/schemas/PluginAssignment" }
                  holders:
                    type: array
                    items: { $ref: "#/components/schemas/PluginHolder" }
                required: [assignments, holders]
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { $ref: "#/components/responses/Upstream" }
    put:
      tags: ["Admin: plugins"]
      summary: Assign plugin access
      operationId: adminAssignPlugin
      description: >-
        Idempotent; re-assigning rewrites the row (the extend path) and never downgrades a long-term grant to
        a temporary one. Groups are standing, so an expiry on a group is refused. 404 for an unknown plugin,
        group, or user (a person in the pool or a registered service user). 409 when the plugin is installed
        but the binding is unavailable (disabled, removed, unsupported, or an unregistered account).
      parameters:
        - $ref: "#/components/parameters/pluginId"
        - $ref: "#/components/parameters/accountNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                principal: { $ref: "#/components/schemas/PluginPrincipal" }
                permission: { $ref: "#/components/schemas/PluginPermission" }
                durationHours: { $ref: "#/components/schemas/DurationHours" }
              required: [principal, permission]
            example: { principal: { kind: user, userId: 6f1e2d3c-0000-4000-8000-000000000001 }, permission: user }
      responses:
        "200":
          description: The stored assignment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignment: { $ref: "#/components/schemas/PluginAssignment" }
                required: [assignment]
        "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" }
        "502": { $ref: "#/components/responses/Upstream" }
    delete:
      tags: ["Admin: plugins"]
      summary: Revoke plugin access
      operationId: adminRevokePlugin
      description: >-
        Idempotent, and deliberately unconditional: a stale row on a disabled or removed plugin stays
        revocable, so availability is not checked first. Holders who lose a capability are noticed.
      parameters:
        - $ref: "#/components/parameters/pluginId"
        - $ref: "#/components/parameters/accountNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                principal: { $ref: "#/components/schemas/PluginPrincipal" }
                permission: { $ref: "#/components/schemas/PluginPermission" }
              required: [principal, permission]
            example: { principal: { kind: group, groupId: platform-team }, permission: admin }
      responses:
        "204": { description: Revoked (or there was nothing to revoke — this is idempotent). }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: The named group does not exist. }
        "409": { $ref: "#/components/responses/Conflict" }
        "502": { $ref: "#/components/responses/Upstream" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A Cognito ID token (humans), a `client_credentials` access token with the `api/invoke` scope (service users), or a personal access token `icpat_<tokenId>_<secret>`.

  parameters:
    accountNumber:
      name: accountNumber
      in: path
      required: true
      schema: { $ref: "#/components/schemas/AccountNumber" }
    roleName:
      name: roleName
      in: path
      required: true
      description: The IAM role name as catalogued (not the ARN).
      schema: { type: string }
    role:
      name: role
      in: path
      required: true
      description: The IAM role name as catalogued (not the ARN).
      schema: { type: string }
    userId:
      name: userId
      in: path
      required: true
      description: A Cognito `sub`, or a service user's client id.
      schema: { type: string }
    requestId:
      name: requestId
      in: path
      required: true
      schema: { type: string }
    groupId:
      name: groupId
      in: path
      required: true
      schema: { type: string }
    resourceId:
      name: resourceId
      in: path
      required: true
      schema: { type: string }
    pluginId:
      name: pluginId
      in: path
      required: true
      description: The plugin's registered id.
      schema: { type: string, pattern: "^[a-z][a-z0-9-]{0,63}$" }
      example: parameters
    clientId:
      name: clientId
      in: path
      required: true
      description: A Cognito app client id (lowercase alphanumerics).
      schema: { type: string, pattern: "^[a-z0-9]{1,128}$" }
    # The list contract (catalog-sized lists): pass `limit` to receive one page — `{ items, nextCursor, total,
    # facets }` — instead of the whole list. Pages are cut in the API from an in-memory catalog index after
    # access is decided, so search is substring-by-token, sorts are any listed key, totals are exact.
    listQ:
      name: q
      in: query
      description: Whitespace-separated tokens; every token must occur (case-insensitive substring) in the row's searchable text (name, number, role names).
      schema: { type: string }
    listFilter:
      name: filter
      in: query
      description: Facet filters, `filter[key]=a,b` (any of the listed values; keys AND together). Each route names its facet keys.
      style: deepObject
      explode: true
      schema:
        type: object
        additionalProperties: { type: string }
    listSort:
      name: sort
      in: query
      description: A sort key the route lists; prefix `-` for descending. Ties break on the row id.
      schema: { type: string }
    listLimit:
      name: limit
      in: query
      description: Page size, 1–200. Present = paged response; absent = the whole list (older clients).
      schema: { type: integer, minimum: 1, maximum: 200 }
    listCursor:
      name: cursor
      in: query
      description: The previous page's `nextCursor`. Opaque; tied to the same `q`/`filter`/`sort` (400 otherwise). Rows inserted or removed between pages are neither skipped nor repeated.
      schema: { type: string }

  responses:
    BadRequest:
      description: Malformed input — the message says which field.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Unauthorized:
      description: Missing, invalid or expired bearer token.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Forbidden:
      description: Admin access required.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    TokenScope:
      description: "A personal access token whose scopes do not reach this route, or any token on a token-management route (`code: TOKEN_SCOPE`)."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/TokenScopeError" }
    NotFound:
      description: The addressed thing does not exist.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Conflict:
      description: Already exists, still in use, or already decided.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotDeployed:
      description: The feature is not deployed on this installation.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Upstream:
      description: A downstream AWS call failed (details stay in the Lambda log).
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    ReportJob:
      type: object
      properties:
        jobId: { type: string, format: uuid }
        kind: { type: string, enum: [accessReport] }
        status: { type: string, enum: [running, done, failed] }
        requestedBy: { type: string }
        startedAt: { type: string, format: date-time }
        finishedAt: { type: string, format: date-time }
        rows: { type: integer, minimum: 0 }
        error: { type: string }
        url: { type: string, format: uri, description: Presigned download, present once `done`; valid 15 minutes. }
      required: [jobId, kind, status, requestedBy, startedAt]
    ListPage:
      type: object
      description: One page of the list contract. `items` is typed per route.
      properties:
        nextCursor: { type: string, description: Pass as `cursor` for the next page; absent on the last page. }
        total: { type: integer, minimum: 0, description: Rows matching `q` and the filters, across all pages. }
        facets:
          type: object
          description: "Per facet key: value → row count over the rows matching `q` and the OTHER facets' filters (so a filtered facet still shows its alternatives)."
          additionalProperties:
            type: object
            additionalProperties: { type: integer }
      required: [total, facets]
    AccountAccessPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            items: { type: array, items: { $ref: "#/components/schemas/AccountAccess" } }
          required: [items]
    RequestableAccountPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            items: { type: array, items: { $ref: "#/components/schemas/RequestableAccount" } }
          required: [items]
    AdminAccountPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            items: { type: array, items: { $ref: "#/components/schemas/AdminAccount" } }
          required: [items]
    UserPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            items: { type: array, items: { $ref: "#/components/schemas/User" } }
          required: [items]
    PluginPermission:
      type: string
      enum: [user, admin]
      description: A plugin's two permission levels. `admin` includes `user` only where the plugin declares `user`.
    PluginPrincipal:
      type: object
      description: Who a plugin assignment is for. Groups are standing — they carry no expiry.
      oneOf:
        - type: object
          properties:
            kind: { type: string, enum: [user] }
            userId: { type: string, description: Cognito sub. }
          required: [kind, userId]
        - type: object
          properties:
            kind: { type: string, enum: [group] }
            groupId: { type: string }
          required: [kind, groupId]
    PluginUnavailableReason:
      type: string
      enum: [plugin-unknown, plugin-disabled, plugin-removed, plugin-unsupported, permission-undeclared, account-unbound, account-unregistered]
      description: Why a stored row cannot authorize anything right now.
    PluginAssignment:
      type: object
      description: One stored grant row, as the editor sees it. A row that is expired or unavailable is kept, shown, and revocable.
      properties:
        pluginId: { type: string }
        accountNumber: { type: string }
        permission: { $ref: "#/components/schemas/PluginPermission" }
        principal: { $ref: "#/components/schemas/PluginPrincipal" }
        grantedBy: { type: string }
        grantedAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        expired: { type: boolean }
        available: { type: boolean, description: Whether this row can authorize anything right now. }
        reason: { $ref: "#/components/schemas/PluginUnavailableReason" }
      required: [pluginId, accountNumber, permission, principal, expired, available]
    PluginCapability:
      type: object
      description: An effective capability, with the stored grants behind it. Implication is applied here, never stored.
      properties:
        pluginId: { type: string }
        accountNumber: { type: string }
        permission: { $ref: "#/components/schemas/PluginPermission" }
        available: { type: boolean }
        reason: { $ref: "#/components/schemas/PluginUnavailableReason" }
        sources:
          type: array
          description: The grants this capability cites — a user capability may cite an admin grant, never the reverse.
          items:
            type: object
            properties:
              permission: { $ref: "#/components/schemas/PluginPermission" }
              groups: { type: array, items: { type: string } }
            required: [permission, groups]
      required: [pluginId, accountNumber, permission, available, sources]
    PluginHolder:
      type: object
      description: Someone who can use the binding right now, directly or through a group.
      properties:
        userId: { type: string }
        email: { type: string }
        capabilities:
          type: array
          items: { $ref: "#/components/schemas/PluginCapability" }
      required: [userId, capabilities]
    UserPluginAccess:
      type: object
      description: A user's stored plugin rows and the capabilities they add up to (direct plus via groups).
      properties:
        assignments:
          type: array
          items: { $ref: "#/components/schemas/PluginAssignment" }
        capabilities:
          type: array
          items: { $ref: "#/components/schemas/PluginCapability" }
      required: [assignments, capabilities]
    PluginDiscoveryUiEntry:
      type: object
      properties:
        label: { type: string }
        icon: { type: string }
        order: { type: integer }
        url: { type: string, description: Absolute path on the portal origin, under the plugin's immutable asset prefix. }
      required: [label, url]
    PluginDiscovery:
      type: object
      description: Caller discovery. An empty list means the feature is off or nothing is registered.
      properties:
        schemaVersion: { type: integer, enum: [1] }
        refreshAfterSeconds: { type: integer, description: How long the portal may keep this before refreshing (15–300). }
        plugins:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              displayName: { type: string }
              description: { type: string }
              version: { type: string }
              revision: { type: string }
              apiBaseUrl: { type: string }
              ui:
                type: object
                properties:
                  user: { $ref: "#/components/schemas/PluginDiscoveryUiEntry" }
                  admin: { $ref: "#/components/schemas/PluginDiscoveryUiEntry" }
              accounts:
                type: array
                items:
                  type: object
                  properties:
                    accountNumber: { type: string }
                    displayName: { type: string, description: From the Accounts catalog, not from any IAM role grant. }
                    regions: { type: array, items: { type: string } }
                    permissions:
                      type: array
                      description: Effective capabilities on this account, not stored assignments.
                      items: { $ref: "#/components/schemas/PluginPermission" }
                  required: [accountNumber, displayName, permissions]
            required: [id, displayName, version, revision, apiBaseUrl, ui, accounts]
      required: [schemaVersion, refreshAfterSeconds, plugins]
    PluginAdminCatalog:
      type: object
      description: Every definition, for the grant editor.
      properties:
        schemaVersion: { type: integer, enum: [1] }
        plugins:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              displayName: { type: string }
              description: { type: string }
              version: { type: string }
              revision: { type: string }
              schemaVersion: { type: integer }
              hostApiVersion: { type: integer }
              status: { type: string, enum: [active, disabled, removed, unsupported] }
              enabled: { type: boolean }
              installed: { type: boolean, description: false = tombstone, kept so historical grants keep their labels. }
              permissions:
                type: array
                items:
                  type: object
                  properties:
                    id: { $ref: "#/components/schemas/PluginPermission" }
                    label: { type: string }
                    description: { type: string }
                    implies:
                      type: array
                      items: { $ref: "#/components/schemas/PluginPermission" }
                  required: [id, label, implies]
              accounts:
                type: array
                items:
                  type: object
                  properties:
                    accountNumber: { type: string }
                    displayName: { type: string }
                    regions: { type: array, items: { type: string } }
                    available: { type: boolean }
                    reason: { type: string, enum: [unregistered] }
                  required: [accountNumber, available]
              ui:
                type: object
                properties:
                  user: { type: object, properties: { label: { type: string }, icon: { type: string }, order: { type: integer } }, required: [label] }
                  admin: { type: object, properties: { label: { type: string }, icon: { type: string }, order: { type: integer } }, required: [label] }
              routes:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: string }
                    method: { type: string }
                    path: { type: string }
                    permission: { $ref: "#/components/schemas/PluginPermission" }
                  required: [id, method, path, permission]
              updatedAt: { type: string, format: date-time }
            required: [id, displayName, version, revision, schemaVersion, hostApiVersion, status, enabled, installed, permissions, accounts, ui, routes, updatedAt]
      required: [schemaVersion, plugins]
    Error:
      type: object
      properties:
        message: { type: string }
      required: [message]
    Message:
      type: object
      properties:
        message: { type: string }
      required: [message]
    Cleared:
      type: object
      properties:
        cleared: { type: integer, description: How many rows were newly marked seen. }
      required: [cleared]
    AccountNumber:
      type: string
      pattern: "^\\d{12}$"
      description: 12-digit AWS account id.
      example: "123456789012"
    DurationHours:
      type: integer
      enum: [1, 12, 24, 72, 168, 720]
      description: Temporary-access preset in hours (1 h, 12 h, 1 d, 3 d, 7 d, 30 d). Omit for long-term access.
    RoleRef:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
      required: [accountNumber, roleName]
    UserIdList:
      type: object
      properties:
        userIds: { type: array, items: { type: string }, minItems: 1 }
      required: [userIds]
    ProfileNameValue:
      type: object
      properties:
        profileName: { type: [string, "null"] }
      required: [profileName]

    Discovery:
      type: object
      properties:
        projectName: { type: string, description: "Empty when unset — clients fall back to the hostname." }
        cognito:
          type: object
          properties:
            userPoolId: { type: string }
            clientId: { type: string }
            region: { type: string }
          required: [userPoolId, clientId, region]
        issuer: { type: string, format: uri, description: The OIDC issuer URL baked into cross-account trust. }
        network:
          type: [object, "null"]
          description: "`null` when no private network is deployed."
          properties:
            controlUrl: { type: string, format: uri, description: Legacy single-site field (first site). }
            sites:
              type: array
              items:
                type: object
                properties:
                  id: { type: string }
                  displayName: { type: string }
                  controlUrl: { type: string, format: uri }
                required: [id, displayName, controlUrl]
          required: [controlUrl, sites]
        personalAccessTokens:
          type: object
          description: Whether this deployment accepts personal access tokens.
          properties:
            enabled: { type: boolean }
          required: [enabled]
      required: [projectName, cognito, issuer, network, personalAccessTokens]

    AccountAccess:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string, description: Admin-set friendly name. }
        environment: { type: string }
        dims: { $ref: "#/components/schemas/AccountDims" }
        sortOrder: { type: integer, minimum: 0, description: Admin-set display position; the list is already in this order. }
        position: { type: integer, minimum: 0, description: Index in the admin order (the `position` sort key). }
        main: { type: boolean, enum: [false], description: Present (false) only for an account an admin took off the dashboard's Main section. }
        roles:
          type: array
          items: { $ref: "#/components/schemas/RoleAccess" }
      required: [accountNumber, position, roles]
    RoleAccess:
      type: object
      properties:
        role: { type: string }
        roleArn: { type: string }
        displayName: { type: string }
        description: { type: string }
        icon: { type: string }
        expiresAt: { type: string, format: date-time, description: End of a temporary grant; absent = long-term. }
        sessionDurationSeconds: { type: integer, minimum: 900, maximum: 43200, description: How long vended credentials for this role last. }
        profileName: { type: string, description: THE `~/.aws` profile name for this role — what the desktop writes. }
        profileSource: { type: string, enum: [override, account, role, default] }
        suggestedProfileName: { type: string, description: What the name would be without the caller's override. }
      required: [role, roleArn, sessionDurationSeconds, profileName, profileSource, suggestedProfileName]
    VendedCredentials:
      type: object
      properties:
        accessKeyId: { type: string }
        secretKey: { type: string }
        sessionToken: { type: string }
        expiration: { type: string, format: date-time, description: When the credentials stop working (the role's session length); cache until shortly before. }
      required: [accessKeyId, secretKey, sessionToken, expiration]
    ConsoleSignIn:
      type: object
      properties:
        url: { type: string, format: uri, description: Short-lived federation sign-in URL. }
        expiration: { type: string, format: date-time }
      required: [url]
    ExpiryNotice:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        expiresAt: { type: string, format: date-time }
        seen: { type: boolean, description: Acknowledged for THIS phase (expiring vs expired). }
      required: [accountNumber, roleName, expiresAt, seen]
    ExpiryNotices:
      type: object
      properties:
        expiring: { type: array, items: { $ref: "#/components/schemas/ExpiryNotice" } }
        expired: { type: array, items: { $ref: "#/components/schemas/ExpiryNotice" } }
      required: [expiring, expired]

    RequestableAccount:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string }
        dims: { $ref: "#/components/schemas/AccountDims" }
        roles:
          type: array
          items:
            type: object
            properties:
              roleName: { type: string }
              displayName: { type: string }
              description: { type: string }
            required: [roleName]
      required: [accountNumber, roles]
    RequestableResource:
      type: object
      properties:
        resourceId: { type: string }
        name: { type: string }
        type: { $ref: "#/components/schemas/ResourceType" }
        description: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        accountName: { type: string }
      required: [resourceId, name, type, accountNumber]
    AccessRequest:
      type: object
      description: One access request or review. `kind` says what is under decision; `type` whether it was raised by a user (`ACCESS`) or by the periodic review sweep (`REAPPROVAL`).
      properties:
        requestId: { type: string }
        userId: { type: string, description: "The requester's sub (reapproval: the holder; group reapproval: the groupId; service-user review: the client id)." }
        kind: { type: string, enum: [ROLE, RESOURCE, ADMIN, SERVICE_USER, PLUGIN, GROUP], description: "PLUGIN = a plugin permission (pluginId + accountNumber + permission); GROUP = the yearly review of a whole group's bundle (userId and groupId are the group; approve restarts its clock, deny deletes the group). Both reapproval-only." }
        type: { type: string, enum: [ACCESS, REAPPROVAL] }
        groupId: { type: string, description: Set on group reapprovals. }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        resourceId: { type: string }
        pluginId: { type: string, description: Set on PLUGIN rows. }
        permission: { type: string, enum: [user, admin], description: Set on PLUGIN rows. }
        resourceName: { type: string, description: Resolved by the route on RESOURCE rows. }
        reason: { type: string }
        requestedDurationHours: { $ref: "#/components/schemas/DurationHours" }
        grantedDurationHours: { $ref: "#/components/schemas/DurationHours" }
        status: { type: string, enum: [PENDING, APPROVED, DENIED] }
        createdAt: { type: string, format: date-time }
        decidedAt: { type: string, format: date-time }
        decidedBy: { type: string }
        decisionNote: { type: string }
        seen: { type: boolean, description: Requester acknowledged the decision. }
      required: [requestId, userId, status, createdAt]
    AccessRequestAdminView:
      allOf:
        - $ref: "#/components/schemas/AccessRequest"
        - type: object
          properties:
            email: { type: string, description: Requester's email; empty if the user is gone. }
            serviceUser: { type: string, description: Registry name when the requester is a service user. }
            group: { type: string, description: Group name on group reapprovals. }
            usage:
              type: object
              description: Only with `?usage=1` on pending role reapprovals.
              properties:
                count: { type: integer }
                lastAt: { type: string, format: date-time }
              required: [count]
          required: [email]
    RequestEnvelope:
      type: object
      properties:
        request: { $ref: "#/components/schemas/AccessRequest" }
      required: [request]

    RolePreference:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        role: { type: string }
        profileName: { type: [string, "null"] }
        roleLabel: { type: [string, "null"] }
        autoVend: { type: boolean }
      required: [accountNumber, role, profileName, roleLabel, autoVend]
    NetworkPrefs:
      type: object
      properties:
        autoReconnect: { type: boolean }
        lastSiteId: { type: [string, "null"] }
      required: [autoReconnect, lastSiteId]

    NotificationPrefs:
      type: object
      properties:
        enabled: { type: boolean, description: Master switch. }
        kinds:
          type: object
          description: Per item kind — granted (a direct grant), revoked, decided (a request decision), expiring (temporary access near or past its end), session (the sign-in is about to reach its cap), requests (admins — a new request waiting), reviews (admins — yearly reviews raised).
          additionalProperties: { type: boolean }
      required: [enabled, kinds]

    PublicSite:
      type: object
      properties:
        id: { type: string }
        displayName: { type: string }
        controlUrl: { type: string, format: uri }
        accounts: { type: array, items: { $ref: "#/components/schemas/AccountNumber" }, description: Accounts in this routing domain. }
      required: [id, controlUrl, accounts]
    NetworkSite:
      allOf:
        - $ref: "#/components/schemas/PublicSite"
        - type: object
          properties:
            splitDns:
              type: object
              additionalProperties: { type: array, items: { type: string } }
              description: Private zone → resolver IPs.
            connectorVpcs:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    vpcId: { type: string }
                    routes: { type: array, items: { type: string } }
                    region: { type: string, description: Set when the VPC is outside the hub's region. }
                    name: { type: string, description: Set for every connector VPC of an account but its one unnamed VPC; suffixes the connector hostname. }
                  required: [vpcId, routes]
              description: Keyed by account number, one entry per connector VPC.
    DevShareGrantee:
      type: object
      properties:
        kind: { type: string, enum: [user, group] }
        id: { type: string }
        name: { type: string, description: Email (user) or group name; the id when the directory no longer knows it. }
      required: [kind, id, name]
    DevShare:
      type: object
      description: A dev share as its owner (or an admin) sees it.
      properties:
        shareId: { type: string, pattern: "^[a-f0-9]{12}$" }
        ownerSub: { type: string }
        ownerName: { type: string, description: The owner's email at creation. }
        port: { type: integer }
        label: { type: string }
        siteId: { type: string }
        hostname: { type: string }
        ip: { type: string }
        device: { type: string, description: The one device the share is bound to; absent = every device of the owner on the site. }
        url:
          type: [string, "null"]
          description: "`http://<hostname|ip>:<port>`; null until the desktop app reported an address."
        createdAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        grantees: { type: array, items: { $ref: "#/components/schemas/DevShareGrantee" } }
      required: [shareId, ownerSub, ownerName, port, label, siteId, url, createdAt, expiresAt, grantees]
    DevShareWithMe:
      type: object
      description: A dev share as a grantee sees it (no grantee list).
      properties:
        shareId: { type: string }
        ownerSub: { type: string }
        ownerName: { type: string }
        port: { type: integer }
        label: { type: string }
        siteId: { type: string }
        url: { type: [string, "null"] }
        expiresAt: { type: string, format: date-time }
        viaGroups:
          type: array
          items: { type: string }
          description: Names of the caller's groups the share came through; empty = granted directly.
      required: [shareId, ownerSub, ownerName, port, label, siteId, url, expiresAt, viaGroups]
    DevShareDirectory:
      type: object
      properties:
        users:
          type: array
          items:
            type: object
            properties:
              userId: { type: string }
              email: { type: string }
            required: [userId, email]
        groups:
          type: array
          items:
            type: object
            properties:
              groupId: { type: string }
              name: { type: string }
              members: { type: integer }
            required: [groupId, name, members]
      required: [users, groups]

    Device:
      type: object
      properties:
        siteId: { type: string }
        name: { type: string, description: The device's name on the site's network. }
        ips: { type: array, items: { type: string } }
        online: { type: boolean }
        lastSeen: { type: string, format: date-time }
        ephemeral: { type: boolean, description: Enrolled with an ephemeral key (removed 30 minutes after going offline). }
      required: [siteId, name, ips, online, ephemeral]

    TokenScopeError:
      type: object
      properties:
        message: { type: string }
        code: { type: string, const: TOKEN_SCOPE }
      required: [message, code]
    TokenScopeName:
      type: string
      enum: [api, aws, network, shares]
    ServiceUserScopeName:
      type: string
      enum: [aws, network, shares, admin.read.all, admin.write.all]
      description: "A service user's scope: `aws` (list its roles, vend credentials, console links), `network` (device keys, its own devices), `shares` (its devices' shares), `admin.read.all` (`GET` under `/admin`), `admin.write.all` (every method under `/admin`; implies `admin.read.all`). Service users never hold the token-only `api`."
    TokenRole:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
      required: [accountNumber, roleName]
    Token:
      type: object
      description: A personal access token as its owner sees it — never the secret.
      properties:
        tokenId: { type: string, pattern: "^[a-f0-9]{16}$" }
        name: { type: string }
        description: { type: string }
        scopes: { type: array, items: { $ref: "#/components/schemas/TokenScopeName" } }
        roles:
          type: array
          items: { $ref: "#/components/schemas/TokenRole" }
          description: The token holds only these of the owner's roles (for `aws` and `api`); absent = all of them.
        createdAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        lastUsedAt: { type: string, format: date-time, description: Updated at most every few minutes. }
      required: [tokenId, name, scopes, createdAt, expiresAt]
    AdminToken:
      allOf:
        - $ref: "#/components/schemas/Token"
        - type: object
          properties:
            ownerId: { type: string }
            ownerEmail: { type: string }
          required: [ownerId]
    TokenExpiryNotice:
      type: object
      properties:
        tokenId: { type: string }
        name: { type: string }
        expiresAt: { type: string, format: date-time }
        seen: { type: boolean }
      required: [tokenId, name, expiresAt, seen]

    DeviceKey:
      type: object
      properties:
        key: { type: string, description: Single-use enrollment key. }
        expiresAt: { type: string, format: date-time }
        controlUrl: { type: string, format: uri }
        siteId: { type: string }
      required: [key, expiresAt, controlUrl, siteId]

    ResourceType:
      type: string
      enum: [DATABASE, WEB, HOST]
    ReachableResource:
      type: object
      properties:
        resourceId: { type: string }
        name: { type: string }
        type: { $ref: "#/components/schemas/ResourceType" }
        cidr: { type: string }
        ports: { type: array, items: { type: integer } }
        dnsName: { type: string }
        sshUser: { type: string }
        description: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        accountName: { type: string }
        expiresAt: { type: string, format: date-time, description: Absent = long-term. }
      required: [resourceId, name, type, cidr, ports, accountNumber]
    PluginExpiryNotice:
      type: object
      properties:
        pluginId: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        permission: { $ref: "#/components/schemas/PluginPermission" }
        expiresAt: { type: string, format: date-time }
        seen: { type: boolean }
        pluginName: { type: string }
        accountName: { type: string }
      required: [pluginId, accountNumber, permission, expiresAt, seen, pluginName, accountName]
    ResourceExpiryNotice:
      type: object
      properties:
        resourceId: { type: string }
        name: { type: string }
        expiresAt: { type: string, format: date-time }
        seen: { type: boolean }
      required: [resourceId, name, expiresAt, seen]
    RevocationNotice:
      type: object
      description: One access change for the bell — a loss, or (since the activity log) a gain the person did not ask for. `revokedAt` is the notice's timestamp either way.
      properties:
        noticeId: { type: string }
        change: { type: string, enum: [GRANTED, REVOKED], description: Rows written before grants were noticed are REVOKED. }
        kind: { type: string, enum: [ROLE, RESOURCE, SHARE, PLUGIN, BUNDLE], description: SHARE = a dev share stopped early (resourceId = share id, resourceName = its label). PLUGIN = a plugin permission lost (pluginId + accountNumber + permission, pluginName = the plugin's display name). BUNDLE = one row for `count` targets that changed together (more than five gained or lost by one person through a group membership or bundle edit, or a cascade); groupId/groupName when a group carried it. Direct admin grants and revokes stay one row per target. }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        resourceId: { type: string }
        resourceName: { type: string }
        pluginId: { type: string }
        permission: { type: string, enum: [user, admin] }
        pluginName: { type: string }
        count: { type: integer, description: BUNDLE only — how many targets the row stands for. }
        groupId: { type: string, description: BUNDLE only — the group whose membership or bundle edit carried the change. }
        groupName: { type: string, description: BUNDLE only — that group's name at the time. }
        revokedAt: { type: string, format: date-time }
        via: { type: string, enum: [ADMIN, GROUP, REAPPROVAL, CASCADE, OWNER] }
        seen: { type: boolean }
      required: [noticeId, change, kind, revokedAt, via, seen]

    SetupStatus:
      type: object
      properties:
        issuerUrl: { type: string, format: uri }
        region: { type: string }
        emailConfigured: { type: boolean }
        emailFrom: { type: string }
        accounts: { type: integer }
        roles: { type: integer }
        usersTotal: { type: integer }
        invitedActive: { type: boolean, description: Someone other than the caller has finished sign-in. }
        vended: { type: boolean, description: At least one successful vend or console-open is on record. }
        configAccounts:
          type: array
          items:
            type: object
            properties:
              accountNumber: { $ref: "#/components/schemas/AccountNumber" }
              roles: { type: array, items: { type: string } }
              registered: { type: boolean }
            required: [accountNumber, roles, registered]
      required: [issuerUrl, region, emailConfigured, accounts, roles, usersTotal, invitedActive, vended, configAccounts]
    BrandingOverlay:
      type: object
      properties:
        projectName: { type: string }
        logoUrl: { type: string, description: "`https://` URL or `data:image/*` URI (≤ 64 KB)." }
        primaryColor: { type: string, pattern: "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }
        primaryHoverColor: { type: string }
        accentColor: { type: string }
        grayTone: { type: string }
        radius: { type: string }
        iconSet: { type: string, enum: [outline, bold, solid] }
        panelStrength: { type: integer, minimum: 0, maximum: 100 }
        accentDepth: { type: integer, minimum: 0, maximum: 100 }
        borderStrength: { type: integer, minimum: 0, maximum: 100 }
        gradientStrength: { type: integer, minimum: 0, maximum: 100 }

    AdminAccount:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string }
        environment: { type: string }
        status: { type: string }
        profileName: { type: string }
        sortOrder: { type: integer, minimum: 0, description: "Display position (PUT /admin/accounts/order); absent = after the ordered ones. The list is already in this order." }
        main: { type: boolean, description: "Shown in everyone's dashboard Main section (the default). Sections appear on a user's dashboard only once they hold an account that is not main." }
        dims: { $ref: "#/components/schemas/AccountDims" }
        position: { type: integer, minimum: 0, description: Index in the admin order (the `position` sort key). }
        roles: { type: array, items: { $ref: "#/components/schemas/AdminRole" } }
      required: [accountNumber, roles]
    AccountDims:
      type: object
      description: |
        Account dimensions (deployments with `accountDimensions` on): read off the name at registration — first hyphen-separated
        segment = tenant, last = stage, the rest = project (`acme-data-platform-prod`; `acme-prod` has no project) — editable by an
        admin afterwards and never re-derived when the account is renamed. They filter lists; they never decide access.
      properties:
        tenant: { type: string, minLength: 1 }
        project: { type: string, minLength: 1 }
        stage: { type: string, minLength: 1 }
      required: [tenant, stage]
    AdminRole:
      type: object
      properties:
        roleName: { type: string }
        displayName: { type: string }
        roleArn: { type: string }
        policyTier: { type: string }
        description: { type: string }
        color: { type: string, description: "Chip tint `#rrggbb`." }
        icon: { type: string, enum: [view, admin, operate, deploy, data, billing, analytics, access] }
        profileName: { type: string }
        sessionDurationSeconds: { type: integer, minimum: 900, maximum: 43200 }
        sortOrder: { type: integer, minimum: 0, description: "Display position inside the account (PUT /admin/accounts/order); absent = after the ordered ones. Lists are already in this order." }
        grantees: { type: integer, description: Unexpired holders (list route only). }
      required: [roleName, roleArn]
    AccountEnvelope:
      type: object
      properties:
        account: { $ref: "#/components/schemas/AdminAccount" }
      required: [account]
    RoleEnvelope:
      type: object
      properties:
        role: { $ref: "#/components/schemas/AdminRole" }
      required: [role]
    ProfileName:
      type: string
      pattern: "^([A-Za-z0-9][A-Za-z0-9_.-]{0,63})?$"
      description: A `~/.aws/credentials` section name (letters, digits, `.`, `_`, `-`); empty string clears.
    AccountCreate:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string }
        environment: { type: string }
        status: { type: string }
        profileName: { $ref: "#/components/schemas/ProfileName" }
        main: { type: boolean, default: true, description: "On everyone's dashboard Main section. A pipeline registering rarely used accounts passes false." }
        dims: { $ref: "#/components/schemas/AccountDims", description: "Explicit dimensions (a pipeline that knows them). Omitted, they are read off `name` when the deployment has account dimensions on." }
      required: [accountNumber]
    AccountOrder:
      type: object
      properties:
        accounts:
          type: array
          minItems: 1
          maxItems: 5000
          items:
            type: object
            properties:
              accountNumber: { $ref: "#/components/schemas/AccountNumber" }
              roles:
                type: array
                maxItems: 200
                uniqueItems: true
                items: { type: string, minLength: 1, maxLength: 64 }
                description: The account's roles, first to last; omit to leave their positions alone.
            required: [accountNumber]
      required: [accounts]
    AccountPatch:
      type: object
      description: At least one field.
      properties:
        name: { type: string }
        environment: { type: string }
        status: { type: string }
        profileName: { $ref: "#/components/schemas/ProfileName" }
        main: { type: boolean, description: "On everyone's dashboard Main section (true is the default state of an account)." }
        dims:
          oneOf:
            - $ref: "#/components/schemas/AccountDims"
            - type: "null"
          description: The admin's correction of tenant / project / stage; `null` clears them. A rename never changes them.
    RoleCreate:
      type: object
      properties:
        roleName: { type: string, description: "May not contain `#` or `/`." }
        displayName: { type: string, maxLength: 128 }
        roleArn: { type: string, pattern: "^arn:aws:iam::\\d{12}:role/.+" }
        policyTier: { type: string }
        description: { type: string }
        color: { type: string, pattern: "^(#[0-9a-fA-F]{6})?$" }
        icon: { type: string, enum: ["", view, admin, operate, deploy, data, billing, analytics, access] }
        profileName: { $ref: "#/components/schemas/ProfileName" }
        sessionDurationSeconds: { type: integer, minimum: 900, maximum: 43200 }
      required: [roleName, roleArn]
    RolePatch:
      type: object
      description: At least one field.
      properties:
        displayName: { type: string, maxLength: 128 }
        roleArn: { type: string, pattern: "^arn:aws:iam::\\d{12}:role/.+" }
        policyTier: { type: string }
        description: { type: string }
        color: { type: string, pattern: "^(#[0-9a-fA-F]{6})?$" }
        icon: { type: string, enum: ["", view, admin, operate, deploy, data, billing, analytics, access] }
        profileName: { $ref: "#/components/schemas/ProfileName" }
        sessionDurationSeconds: { type: integer, minimum: 900, maximum: 43200 }
    TestSessionResult:
      type: object
      properties:
        ok: { type: boolean }
        message: { type: string, description: STS's message when `ok` is false. }
        expiration: { type: string, format: date-time }
      required: [ok]

    Grant:
      type: object
      properties:
        userId: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        expiresAt: { type: string, format: date-time, description: Absent = long-term. }
      required: [userId, accountNumber, roleName]
    Grantee:
      type: object
      properties:
        userId: { type: string }
        grantedBy: { type: string }
        grantedAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        direct: { type: boolean, description: Holds a direct grant row. }
        viaGroup: { type: string, description: First group providing it when there is no direct grant. }
        viaGroups: { type: array, items: { type: string }, description: Every group of theirs whose bundle holds it. }
      required: [userId, direct, viaGroups]
    UserGrant:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        grantedBy: { type: string }
        grantedAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time, description: Effective expiry; absent when long-term or group-provided. }
        viaGroup: { type: string }
        viaGroups: { type: array, items: { type: string } }
      required: [accountNumber, roleName]
    BulkAssignResult:
      type: object
      properties:
        userId: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        status: { type: string, enum: [GRANTED, ALREADY_HAD, FAILED] }
        message: { type: string }
      required: [userId, accountNumber, roleName, status]
    BulkRevokeResult:
      type: object
      properties:
        userId: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        roleName: { type: string }
        status: { type: string, enum: [REVOKED, SKIPPED, FAILED] }
        message: { type: string }
      required: [userId, accountNumber, roleName, status]

    User:
      type: object
      properties:
        userId: { type: string, description: "Cognito `sub` — the stable id grants are keyed by." }
        email: { type: string }
        admin: { type: boolean }
        pendingInvite: { type: boolean, description: Invited and never signed in — still on the temporary password, and not seen through a federated sign-in either. }
        lastSeenAt: { type: string, format: date-time }
        claims:
          type: object
          additionalProperties: { type: string }
          description: "Federated claims on the user, keyed by the config `claims` key (e.g. `gid`). Only when at least one is set."
        roleCount: { type: integer, minimum: 0, description: "Every role the user holds; `roles` carries at most 50 of them in the listing." }
        resourceCount: { type: integer, minimum: 0, description: "Every resource the user holds; `resources` carries at most 50 of them in the listing." }
        roleNames: { type: array, items: { type: string }, description: "Distinct role names over every role held (listing only) — complete where `roles` is cut." }
        groupNames: { type: array, items: { type: string }, description: Distinct team names over every role and resource held (listing only). }
        roles:
          type: array
          items:
            type: object
            properties:
              accountNumber: { $ref: "#/components/schemas/AccountNumber" }
              roleName: { type: string }
              direct: { type: boolean }
              groups: { type: array, items: { type: string }, description: Names of the user's groups whose bundle also grants it. }
            required: [accountNumber, roleName, direct, groups]
        resources:
          type: array
          items:
            type: object
            properties:
              resourceId: { type: string }
              name: { type: string }
              accountNumber: { $ref: "#/components/schemas/AccountNumber" }
              direct: { type: boolean }
              groups: { type: array, items: { type: string } }
            required: [resourceId, name, direct, groups]
      required: [userId, email, admin, pendingInvite, roles, resources]
    BulkCreateResult:
      type: object
      properties:
        email: { type: string }
        status: { type: string, enum: [CREATED, FAILED] }
        userId: { type: string }
        signupLink: { type: string, description: "On CREATED rows when `sendEmail` was `false`." }
        message: { type: string }
      required: [email, status]
    BulkDeleteResult:
      type: object
      properties:
        userId: { type: string }
        status: { type: string, enum: [DELETED, FAILED] }
        message: { type: string }
      required: [userId, status]

    ServiceUser:
      type: object
      properties:
        clientId: { type: string }
        name: { type: string }
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
        lastUsedAt: { type: string, format: date-time }
        secretCreatedAt: { type: string, format: date-time }
        reviewedAt: { type: string, format: date-time }
        scopes: { type: array, items: { $ref: "#/components/schemas/ServiceUserScopeName" }, description: "Routes its tokens may call. Always present: a row from before scopes existed reads as the full set (`aws`, `network`, `shares`, `admin.write.all`)." }
        roles: { type: array, items: { $ref: "#/components/schemas/UserGrant" } }
        previous:
          type: object
          description: Mid-rotation — the replaced client that still works.
          properties:
            clientId: { type: string }
            rotatedAt: { type: string, format: date-time }
            lastUsedAt: { type: string, format: date-time }
          required: [clientId]
      required: [clientId, name, createdAt, createdBy, scopes, roles]
    ServiceUserWithSecret:
      type: object
      properties:
        serviceUser: { $ref: "#/components/schemas/ServiceUser" }
        clientSecret: { type: string, description: Returned exactly once. }
      required: [serviceUser, clientSecret]

    GroupInput:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 64 }
        description: { type: string, maxLength: 500 }
        roles: { type: array, items: { $ref: "#/components/schemas/RoleRef" } }
        resources: { type: array, items: { type: string }, description: Resource ids. }
    Group:
      type: object
      properties:
        groupId: { type: string }
        name: { type: string }
        description: { type: string }
        roles: { type: array, items: { $ref: "#/components/schemas/RoleRef" }, description: "In the list, at most 50 of them; `roleCount` is the total and GET /admin/groups/{groupId} carries all." }
        roleCount: { type: integer, minimum: 0 }
        resources: { type: array, items: { type: string }, description: Resource ids. }
        plugins:
          type: array
          description: Plugin permissions in the bundle.
          items:
            type: object
            properties:
              pluginId: { type: string }
              accountNumber: { $ref: "#/components/schemas/AccountNumber" }
              permission: { type: string, enum: [user, admin] }
            required: [pluginId, accountNumber, permission]
        members: { type: array, items: { type: string }, description: Cognito subs, sorted. }
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
      required: [groupId, name, roles, resources, plugins, members, createdAt, createdBy]
    GroupView:
      type: object
      properties:
        groupId: { type: string }
        name: { type: string }
        description: { type: string }
        roles: { type: array, items: { $ref: "#/components/schemas/RoleRef" } }
        resources:
          type: array
          items:
            type: object
            properties:
              resourceId: { type: string }
              name: { type: string }
            required: [resourceId, name]
        members:
          type: array
          items:
            type: object
            properties:
              userId: { type: string }
              email: { type: string }
            required: [userId, email]
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
      required: [groupId, name, roles, resources, members, createdAt, createdBy]
    GroupEnvelope:
      type: object
      properties:
        group: { $ref: "#/components/schemas/Group" }
      required: [group]
    GroupRoleChange:
      type: object
      description: One role in or out of a bundle — what changed, never the bundle itself.
      properties:
        groupId: { type: string }
        name: { type: string }
        role: { $ref: "#/components/schemas/GroupRoleRef" }
        added: { type: boolean, description: "False when the role was already in the bundle." }
      required: [groupId, name, role, added]
    GroupRolesBulkResult:
      type: object
      properties:
        matched: { type: integer, description: Accounts matching the filter that have the role. }
        added: { type: integer, description: Rows written (absent on a dry run). }
        skipped: { type: integer, description: Matches already in the bundle (absent on a dry run). }
        remaining: { type: integer, description: "Matches not yet written: one call writes at most 500, call again until this is 0 (absent on a dry run)." }
        group: { $ref: "#/components/schemas/Group" }
      required: [matched]

    Resource:
      type: object
      properties:
        resourceId: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string }
        type: { $ref: "#/components/schemas/ResourceType" }
        cidr: { type: string, description: "Always `a.b.c.d/nn` with 24 ≤ nn ≤ 32." }
        ports: { type: array, items: { type: integer } }
        dnsName: { type: string, description: Connect name shown to users; the reconciler re-resolves it each pass. }
        sshUser: { type: string }
        securityGroupId: { type: string, description: When set, the reconciler keeps a connector ingress rule in it. }
        description: { type: string }
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
      required: [resourceId, accountNumber, name, type, cidr, ports, createdAt, createdBy]
    ResourceCreate:
      type: object
      properties:
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        name: { type: string }
        type: { $ref: "#/components/schemas/ResourceType" }
        cidr: { type: string, description: Bare IPv4 or /16–/32 CIDR. }
        ports: { type: array, items: { type: integer, minimum: 1, maximum: 65535 }, minItems: 1 }
        dnsName: { type: string }
        sshUser: { type: string }
        securityGroupId: { type: string }
        description: { type: string }
      required: [accountNumber, name, type, cidr, ports]
    ResourcePatch:
      type: object
      description: At least one field.
      properties:
        name: { type: string }
        type: { $ref: "#/components/schemas/ResourceType" }
        cidr: { type: string }
        ports: { type: array, items: { type: integer, minimum: 1, maximum: 65535 }, minItems: 1 }
        dnsName: { type: string }
        sshUser: { type: string }
        securityGroupId: { type: string }
        description: { type: string }
    ResourceEnvelope:
      type: object
      properties:
        resource: { $ref: "#/components/schemas/Resource" }
      required: [resource]
    ResourceGrantee:
      type: object
      properties:
        userId: { type: string }
        email: { type: string }
        grantedBy: { type: string }
        grantedAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        direct: { type: boolean }
        viaGroup: { type: string }
        viaGroups: { type: array, items: { type: string } }
      required: [userId, email, direct, viaGroups]
    UserResourceGrant:
      type: object
      properties:
        resourceId: { type: string }
        grantedBy: { type: string }
        grantedAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        viaGroup: { type: string }
        viaGroups: { type: array, items: { type: string } }
      required: [resourceId]
    UserResourceGrantNamed:
      allOf:
        - $ref: "#/components/schemas/UserResourceGrant"
        - type: object
          properties:
            resourceName: { type: string }
          required: [resourceName]

    ReconcilerStatus:
      type: object
      properties:
        at: { type: [string, "null"], format: date-time, description: Oldest site pass; `null` = never ran. }
        resources:
          type: object
          description: Keyed by resourceId.
          additionalProperties:
            type: object
            properties:
              status: { type: string }
              users: { type: integer }
              sg: { type: string, description: "SG-manager verdict for the resource's security group: ok, not-found, invalid, error, other-vpc (the group is in none of the account's connector VPCs), sg-sync-failed." }
              sgId: { type: string }
              addr: { type: string, enum: [dns, dns-stale] }
              addrIp: { type: string }
              addrName: { type: string }
            required: [status]
        staleConnectors: { type: array, items: { type: string } }
        resourcesLive: { type: integer }
        rules: { type: integer }
        shares:
          type: object
          description: Dev shares keyed by shareId — `live` (users = enrolled grantees named) or why not (`owner-not-enrolled`, `no-grantees`, `no-enrolled-grantees`, `invalid-port`).
          additionalProperties:
            type: object
            properties:
              status: { type: string }
              users: { type: integer }
            required: [status]
        sharesLive: { type: integer }
        sites:
          type: object
          additionalProperties:
            type: object
            properties:
              at: { type: [string, "null"], format: date-time }
              staleConnectors: { type: array, items: { type: string } }
              resourcesLive: { type: integer }
              rules: { type: integer }
              sharesLive: { type: integer }
            required: [at, staleConnectors, resourcesLive, rules]
        connectors:
          type: array
          items:
            type: object
            properties:
              siteId: { type: string }
              account: { type: string }
              name: { type: string }
              vpcName: { type: string, description: Which of the account's connector VPCs (its config name); absent = the unnamed one. }
              nodeId: { type: string }
              trusted: { type: boolean }
              online: { type: boolean }
              lastSeen: { type: string, format: date-time }
              advertisedRoutes: { type: array, items: { type: string } }
              approvedRoutes: { type: array, items: { type: string } }
            required: [siteId, account, name, trusted, online, advertisedRoutes, approvedRoutes]
        devices:
          type: object
          description: Keyed by user sub.
          additionalProperties:
            type: object
            properties:
              count: { type: integer }
              online: { type: boolean }
              lastSeen: { type: string, format: date-time }
              sites: { type: array, items: { type: string } }
            required: [count, online, sites]
      required: [at, resources, staleConnectors, resourcesLive, rules, connectors, devices]

    ActivityActor:
      type: object
      properties:
        kind: { type: string, enum: [user, service, system] }
        id: { type: string, description: Cognito sub, app client id, or `system:<job>`. }
        name: { type: string, description: The live directory name when the caller still exists, else the write-time snapshot. }
        claims:
          type: object
          additionalProperties: { type: string }
        deleted: { type: boolean, description: Present when the caller is no longer in the directory. }
      required: [kind, id]
    ActivitySubject:
      type: object
      properties:
        kind: { type: string, enum: [user, group, serviceUser] }
        id: { type: string }
        name: { type: string }
        deleted: { type: boolean }
      required: [kind, id]
    ActivityEventView:
      type: object
      description: One recorded action. `action` is `object.verb` (role.grant, request.approve, credentials.vend, vpn.connect, admin.access, …); `outcome` says whether it happened.
      properties:
        eventId: { type: string }
        category: { type: string, enum: [access, request, vend, network, catalog, users, auth] }
        action: { type: string }
        outcome: { type: string, enum: [OK, DENIED, FAILED] }
        reason: { type: string, description: Caller-safe cause on DENIED and FAILED rows. }
        actor: { $ref: "#/components/schemas/ActivityActor" }
        subject: { $ref: "#/components/schemas/ActivitySubject" }
        target: { type: string, description: "`role#<account>#<name>`, `resource#<id>`, `plugin#<id>#<account>#<permission>`, `share#<id>`, `group#<id>`, `user#<sub>`, `serviceuser#<id>`, `account#<n>`, `site#<id>`, `sg#<id>`, `route#<METHOD /path>`." }
        targetName: { type: string }
        accountNumber: { $ref: "#/components/schemas/AccountNumber" }
        details:
          type: object
          description: expiresAt, durationHours, note, via (ADMIN | GROUP | REAPPROVAL | CASCADE | OWNER | EXPIRY), groupId, requestId, batchId, changed (key → {from, to}), affected (up to 50 {userId, name, change}) + affectedCount, deniedReason, and action-specific keys.
          additionalProperties: true
        derived: { type: boolean, description: A per-user effective-access change the access diff wrote (access.gain / access.lose), linked to its batch's primary row. }
        at: { type: string, format: date-time }
        day: { type: string, description: UTC calendar day `YYYY-MM-DD`. }
      required: [eventId, category, action, outcome, actor, at, day]
    ActivityPage:
      type: object
      properties:
        events:
          type: array
          items: { $ref: "#/components/schemas/ActivityEventView" }
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        nextBefore: { type: string, format: date-time, description: Present when the page filled up — pass as `before` (with `skip`) to continue. }
      required: [events, from, to]