@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
YAML
# 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]