Admin: governance
Endpoints under /api/admin power the console's Admin area. They need an admin role:
| Role | Access |
|---|---|
| Org Admin | Read and change everything |
| Auditor | Read everything; every change answers 403 |
| Delegated Admin | Projects, cost and audit events in their part of the org |
Anyone else gets 403 FORBIDDEN ("Org Admins only."). The roles themselves are explained in Administration.
Me
GET /api/admin/me
{ user: { id, name, email }, roles }, where roles is { orgAdmin, auditor, approver, builder, delegated }.
Projects
| Method | Path | Body / query | What it does |
|---|---|---|---|
GET | /api/admin/projects | ?q=&month=YYYY-MM | Every project you govern, with owner, cost and deployment count. q matches project name, owner name or email. |
GET | /api/admin/projects/:name | The project drawer: detail, owner, cost, lifecycle | |
POST | /api/admin/projects/:name/disable | { reason } | Kill switch: stop serving the app |
POST | /api/admin/projects/:name/enable | Re-enable a disabled project | |
POST | /api/admin/projects/:name/archive | { reason? } | Archive (default reason "archived by IT") |
POST | /api/admin/projects/:name/restore | Restore an archived project | |
POST | /api/admin/projects/:name/transfer | { to } | Hand to another person (email or id) |
POST | /api/admin/users/:id/disable-projects | { reason } | Per-person kill switch: disable every project this person owns |
POST | /api/admin/users/:id/enable-projects | Undo the per-person kill switch |
Org tree and directory sync
| Method | Path | Query | What it does |
|---|---|---|---|
GET | /api/admin/org/tree | hierarchy=reporting|department|group, month | The org tree with projects placed where their owners sit, and rollups |
GET | /api/admin/org/sync | limit (default 20) | Recent directory sync runs |
POST | /api/admin/org/sync | Sync the directory now |
Cost
| Method | Path | Query | What it does |
|---|---|---|---|
GET | /api/admin/cost | month, groupBy (department default, reporting, group, project), node | Cost breakdown |
GET | /api/admin/cost/trend | months (default 6), month | Monthly trend |
GET | /api/admin/cost/export.csv | month | Chargeback CSV (chargeback-YYYY-MM.csv) |
POST | /api/admin/cost/pull | Pull cost data now |
Roles
| Method | Path | Body | What it does |
|---|---|---|---|
GET | /api/admin/roles | Role assignments | |
POST | /api/admin/roles | { role, principal, scope? } | Assign a role. 201 { assignment }. |
DELETE | /api/admin/roles/:id | Remove an assignment: { removed } |
role is org_admin, delegated_admin, approver, builder or auditor. principal is an email, a group name or { type: "user" | "group", id }. scope (for delegated admins) is { type: "department", department: "Finance" } or { type: "subtree", user: "<email or id>" }.
{ "role": "delegated_admin", "principal": "priya.raman@contoso.com", "scope": { "type": "department", "department": "Finance" } }
Platform settings and lifecycle
| Method | Path | Body | What it does |
|---|---|---|---|
GET | /api/admin/settings | Platform settings | |
PUT | /api/admin/settings | { lifecycle?, buildersEveryone? } | Lifecycle rules (when idle projects are flagged and archived) and whether everyone may build |
POST | /api/admin/lifecycle/run | { now? } | Run the lifecycle job now. now lets local installs simulate a date. |
PUT and DELETE /api/admin/dev/directory/users/:id simulate directory changes (for example someone leaving) on local installs, followed by POST /api/admin/org/sync. They're for demos and tests only.
Audit log
GET /api/admin/audit?q=&project=:name&limit=50&before=:id
Newest first. limit up to 500; page with before set to the previous response's nextBefore. Delegated Admins see events of projects in their scope.
Response 200: { "events": [ … ], "nextBefore": 1234 }. Errors: 400 BAD_CURSOR.
Integration catalog
| Method | Path | Body | Who | What it does |
|---|---|---|---|---|
GET | /api/admin/integrations | Org Admin, Auditor | Every integration with grant, pending-request and 30-day call counts | |
PUT | /api/admin/integrations/:name | { displayName?, description?, enabled?, approvers?, maxScopes?, sensitivity?, mode?, config? } | Org Admin | Update an integration |
approvers are emails or group names. sensitivity is low, medium or high. In config, keys that look like secrets (secret, password, token, connectionString) are sealed and never returned; null removes a key.
Approval policies
| Method | Path | Body | Who |
|---|---|---|---|
GET | /api/admin/policies | Org Admin, Auditor | |
POST | /api/admin/policies | { name, description?, enabled?, effect?, match? } | Org Admin |
PUT | /api/admin/policies/:id | { name?, description?, enabled?, effect?, match? } | Org Admin |
DELETE | /api/admin/policies/:id | Org Admin |
effect is auto_approve (default) or require_manager. Each policy comes back with a plain-English summary. Built-in policies can't be deleted (400 CANNOT_DELETE); turn them off instead.