Skip to main content

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"] }
}
FieldDescription
modeonly_me, team, department, groups or everyone
membersReplaces the list. A member is a user email or id, a group name or id, user:<id>, group:<id>, or { "type", "id" }.
rolesApp 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​

MethodPathBodyAuthWhat it does
POST/api/projects/:name/archiveownArchives the project
POST/api/projects/:name/restoreownRestores an archived app
POST/api/projects/:name/transfer{ "to": "<email or id>" }ownHands 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": [ … ] }.

Was this page helpful?