Access and settings
Access
Get access
GET /api/projects/:name/access
Who can open the app. Auth: view.
Response 200
{
"project": "expenses",
"mode": "groups",
"owner": { "id": "…", "name": "Isabel Moreno", "email": "isabel.moreno@contoso.com" },
"members": [{ "type": "group", "id": "…", "name": "Operations" }],
"roles": { "approver": [{ "type": "user", "id": "…", "name": "henrik.larsen@contoso.com" }] },
"live": null
}
For team and department, live shows what the rule resolves to now (team.size, team.manager, department.name, department.size).
Set access
PUT /api/projects/:name/access
{
"mode": "groups",
"members": ["Operations", "kwame.mensah@contoso.com"],
"roles": { "approver": ["henrik.larsen@contoso.com"] }
}
| Field | Description |
|---|---|
mode | only_me, team, department, groups or everyone |
members | Replaces the list. A member is a user email or id, a group name or id, user:<id>, group:<id>, or { "type", "id" }. |
roles | App role → members. Roles reach the app in the user's roles. |
Omitted fields keep their value. Auth: manage; audited.
Response 200: the access view, as above.
Errors: 400 INVALID_ACCESS (unknown mode, or groups with nobody listed), 400 UNKNOWN_PRINCIPAL, 403 READ_ONLY.
Recent opens
GET /api/projects/:name/opens?days=30
Who opened the app recently (up to 50 entries). Auth: view.
Settings
Get settings
GET /api/projects/:name/settings
The console's Settings page in one call. Auth: view.
Response 200: { project, perms, general: { name, url, createdAt, createdBy, owner, lifecycle, lifecycleReason, productionDeploymentId, serviceType }, expiry, domains, … }.
Renew
POST /api/projects/:name/renew
Resets the inactivity clock that would otherwise archive the project. Auth: own.
Response 200: { "expiry": { … } }. Errors: 409 PROJECT_NOT_ACTIVE.
Environment variables
List
GET /api/projects/:name/env
Response 200
{
"project": "expenses",
"vars": [
{ "name": "SUPPORT_EMAIL", "secret": false, "value": "support@contoso.com", "masked": null, "updatedAt": "…", "updatedBy": { "id": "…", "name": "Isabel Moreno" } },
{ "name": "SLACK_WEBHOOK", "secret": true, "value": null, "masked": "••••••••", "updatedAt": "…", "updatedBy": { "…": "…" } }
],
"pendingRedeploy": true,
"staticSite": false
}
Secret values are never returned. People with view-only access see every value masked.
Set
PUT /api/projects/:name/env
{ "vars": [{ "name": "SUPPORT_EMAIL", "value": "support@contoso.com" }, { "name": "SLACK_WEBHOOK", "value": "https://…", "secret": true }] }
A single { "name", "value", "secret" } object works too. Auth: manage; audited by name only.
Response 200: the list, plus changed: ["SUPPORT_EMAIL", …].
Errors: 400 INVALID_ENV (reserved name such as TC_*, DATABASE_URL, PORT; invalid name; value over 32 KB), 400 TOO_MANY_ENV (over 100).
Unset
DELETE /api/projects/:name/env/:var
Response 200: the list plus removed. Errors: 404 ENV_NOT_FOUND.
Redeploy
POST /api/projects/:name/redeploy
Redeploys the current production build with the current env. No rebuild. Auth: manage.
Response 202: { "project", "deployment": Deployment, "from": "d8f3a2" }.
Errors: 409 NO_PRODUCTION, 409 STATIC_SITE, 409 PROJECT_NOT_ACTIVE.
Lifecycle and ownership
| Method | Path | Body | Auth | What it does |
|---|---|---|---|---|
POST | /api/projects/:name/archive | own | Archives the project | |
POST | /api/projects/:name/restore | own | Restores an archived app | |
POST | /api/projects/:name/transfer | { "to": "<email or id>" } | own | Hands the project to another active person |
Archive and restore return { project, lifecycle, changed }; transfer returns { project, owner }.
Errors: 409 PROJECT_DISABLED (IT disabled it; ask IT), 409 WRONG_STATE, 400 UNKNOWN_USER, 409 ALREADY_OWNER.
Delete a project
DELETE /api/projects/:name
{ "confirm": "expenses" }
Deletes the app, preview URLs, database and files for good; cancels pending access requests; keeps an audit record. confirm can also be a query parameter. Idempotent: deleting an already deleted project returns alreadyDeleted: true. Auth: own.
Response 200: { …, "teardown": "done" | "running" }.
Errors: 400 CONFIRM_MISMATCH, 403 FORBIDDEN / 403 READ_ONLY.
Project audit log
GET /api/projects/:name/audit?action=ACTION&limit=50
Auth: view. Response 200: { "events": [ … ] }.