Skip to main content

Admin: governance

Endpoints under /api/admin power the console's Admin area. They need an admin role:

RoleAccess
Org AdminRead and change everything
AuditorRead everything; every change answers 403
Delegated AdminProjects, 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​

MethodPathBody / queryWhat it does
GET/api/admin/projects?q=&month=YYYY-MMEvery project you govern, with owner, cost and deployment count. q matches project name, owner name or email.
GET/api/admin/projects/:nameThe project drawer: detail, owner, cost, lifecycle
POST/api/admin/projects/:name/disable{ reason }Kill switch: stop serving the app
POST/api/admin/projects/:name/enableRe-enable a disabled project
POST/api/admin/projects/:name/archive{ reason? }Archive (default reason "archived by IT")
POST/api/admin/projects/:name/restoreRestore 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-projectsUndo the per-person kill switch

Org tree and directory sync​

MethodPathQueryWhat it does
GET/api/admin/org/treehierarchy=reporting|department|group, monthThe org tree with projects placed where their owners sit, and rollups
GET/api/admin/org/synclimit (default 20)Recent directory sync runs
POST/api/admin/org/syncSync the directory now

Cost​

MethodPathQueryWhat it does
GET/api/admin/costmonth, groupBy (department default, reporting, group, project), nodeCost breakdown
GET/api/admin/cost/trendmonths (default 6), monthMonthly trend
GET/api/admin/cost/export.csvmonthChargeback CSV (chargeback-YYYY-MM.csv)
POST/api/admin/cost/pullPull cost data now

Roles​

MethodPathBodyWhat it does
GET/api/admin/rolesRole assignments
POST/api/admin/roles{ role, principal, scope? }Assign a role. 201 { assignment }.
DELETE/api/admin/roles/:idRemove 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>" }.

POST /api/admin/roles
{ "role": "delegated_admin", "principal": "priya.raman@contoso.com", "scope": { "type": "department", "department": "Finance" } }

Platform settings and lifecycle​

MethodPathBodyWhat it does
GET/api/admin/settingsPlatform 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.
Availability

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​

MethodPathBodyWhoWhat it does
GET/api/admin/integrationsOrg Admin, AuditorEvery integration with grant, pending-request and 30-day call counts
PUT/api/admin/integrations/:name{ displayName?, description?, enabled?, approvers?, maxScopes?, sensitivity?, mode?, config? }Org AdminUpdate 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​

MethodPathBodyWho
GET/api/admin/policiesOrg 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/:idOrg 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.

Was this page helpful?