Members, roles and tokens

Who can do what in a project: members, roles, environment rules, tokens, notification settings and the audit log.

`GET /api/v1/me`

Who the caller is: memberships with their permissions, the environment rules that apply, and the project a token is pinned to, if any.

Status	Means	Body
200	Done	MeResponse
401	No token, or a token that is not valid

`DELETE /api/v1/me/mfa`

Drop the caller's own enrolment.

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
409	It conflicts with what is there

`POST /api/v1/me/mfa/confirm`

Prove one code from the staged seed and the enrolment is in force. A wrong code and a replayed code are the same 401, deliberately.

Body: MfaConfirmBody

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
409	Nothing is waiting to be confirmed
503	The secrets store is sealed

`POST /api/v1/me/mfa/enrol`

Start an enrolment: a fresh seed, staged but not yet in force. The account is only protected once a code from it verifies, so this call alone locks nobody out and can be repeated.

Status	Means	Body
200	Done	MfaEnrolResponse
401	No token, or a token that is not valid
409	This account already has an authenticator enrolled
503	The secrets store is sealed

`GET /api/v1/me/sessions`

The caller's own live sessions: every browser and CLI they are signed in on.

Status	Means	Body
200	Done	array of SessionResponse
401	No token, or a token that is not valid

`DELETE /api/v1/me/sessions/{session_id}`

Sign one of the caller's own sessions out.

Parameter	In	Type	About
`session_id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
404	Not found

`GET /api/v1/notifications`

The caller's feed, newest first.

Parameter	In	Type	About
`unread` (optional)	query	boolean or null
`project` (optional)	query	string or null	A project slug, matched against the notice's own `project` param.
`limit` (optional)	query	integer or null	Default 50, maximum 200.
`cursor` (optional)	query	string or null

Status	Means	Body
200	Done	array of NotificationResponse
401	No token, or a token that is not valid

`POST /api/v1/notifications/read-all`

Mark the whole feed read. Idempotent, and never an error on an empty feed.

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid

`GET /api/v1/notifications/unread-count`

How many notifications the caller has not read.

Status	Means	Body
200	Done	UnreadCountResponse
401	No token, or a token that is not valid

`POST /api/v1/notifications/{id}/read`

Mark one notice read.

Parameter	In	Type	About
`id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
404	Not found

`GET /api/v1/permissions`

The 28 permissions, in console order with the groups contiguous, so the Roles page renders the toggles without sorting anything.

Status	Means	Body
200	Done	array of PermissionResponse
401	No token, or a token that is not valid

`GET /api/v1/projects/{slug}/audit`

One project's audit log: the same trail with the project pinned, so a project page can show its own refusals.

Parameter	In	Type	About
`slug`	path	string
`actor` (optional)	query	string or null
`project` (optional)	query	string or null	Ignored on the project route: the path pins the project there.
`environment` (optional)	query	string or null
`action` (optional)	query	string or null
`outcome` (optional)	query	string or null	allowed \| denied. Absent = both.
`since` (optional)	query	string or null
`limit` (optional)	query	integer or null	Default 100, maximum 500.
`cursor` (optional)	query	integer or null

Status	Means	Body
200	Done	array of AuditResponse
403	Your role does not allow this
404	No such project

`GET /api/v1/projects/{slug}/environment-policies`

Every policy in the project, for its Environment access panel.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of EnvironmentPolicyResponse
401	No token, or a token that is not valid
403	Your role does not allow this

`PUT /api/v1/projects/{slug}/environment-policies/{environment}/{role_id}`

Write a policy.

Parameter	In	Type
`slug`	path	string
`environment`	path	string
`role_id`	path	string (uuid)

Body: WritePolicyBody

Status	Means	Body
200	Done	EnvironmentPolicyResponse
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	The fixed role
422	Refused, and the error says why

`DELETE /api/v1/projects/{slug}/environment-policies/{environment}/{role_id}`

Remove a policy, which gives the role its full set back in that environment.

Parameter	In	Type
`slug`	path	string
`environment`	path	string
`role_id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found

`GET /api/v1/projects/{slug}/members`

The project's members with their roles.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of MemberResponse
401	No token, or a token that is not valid
403	Your role does not allow this

`POST /api/v1/projects/{slug}/members`

Add a member. One membership per operator per project, so adding someone who is already a member changes their role rather than failing.

Parameter	In	Type	About
`slug`	path	string

Body: WriteMembershipBody

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	It conflicts with what is there

`GET /api/v1/projects/{slug}/members/candidates`

The people who can be added as members of the project.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of CandidateResponse
401	No token, or a token that is not valid
403	Your role does not allow this

`PUT /api/v1/projects/{slug}/members/{operator_id}`

Change one member's role. The path names the operator; a mismatched operator_id in the body is ignored, because the path is what was authorized.

Parameter	In	Type	About
`slug`	path	string
`operator_id`	path	string (uuid)

Body: WriteMembershipBody

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	It conflicts with what is there

`DELETE /api/v1/projects/{slug}/members/{operator_id}`

Take a project membership away.

Parameter	In	Type	About
`slug`	path	string
`operator_id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found

`GET /api/v1/projects/{slug}/notification-settings`

The caller's notification settings for this project, one for each kind of notice.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of NotificationSettingResponse
403	Your role does not allow this
404	No such project

`PUT /api/v1/projects/{slug}/notification-settings`

Replace the caller's notification settings for this project.

Parameter	In	Type	About
`slug`	path	string

Body: WriteNotificationSettingsBody

Status	Means	Body
204	Done, with no body
403	Your role does not allow this
404	No such project
422	Unknown notification kind

`GET /api/v1/projects/{slug}/roles`

The roles every project has, plus the ones this project defined.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of RoleResponse
401	No token, or a token that is not valid
403	Your role does not allow this

`POST /api/v1/projects/{slug}/roles`

Create a role this project owns. The path decides the project; a project in the body is ignored, because the permission that let this call through is project.members in THIS project.

Parameter	In	Type	About
`slug`	path	string

Body: WriteRoleBody

Status	Means	Body
201	Created	RoleResponse
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	It conflicts with what is there
422	Refused, and the error says why

`PUT /api/v1/projects/{slug}/roles/{id}`

Change a role this project defined: its name and its permissions.

Parameter	In	Type	About
`slug`	path	string
`id`	path	string (uuid)

Body: WriteRoleBody

Status	Means	Body
200	Done	RoleResponse
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	It conflicts with what is there
422	Refused, and the error says why

`DELETE /api/v1/projects/{slug}/roles/{id}`

Remove a role this project defined.

Parameter	In	Type	About
`slug`	path	string
`id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
403	Your role does not allow this
404	Not found
409	That role still has members

`GET /api/v1/projects/{slug}/tokens`

Every token pinned to this project, for its settings page.

Parameter	In	Type	About
`slug`	path	string

Status	Means	Body
200	Done	array of TokenResponse
401	No token, or a token that is not valid
403	Your role does not allow this

`GET /api/v1/tokens`

The caller's own tokens, and every token when the caller manages people.

Status	Means	Body
200	Done	array of TokenResponse
401	No token, or a token that is not valid

`POST /api/v1/tokens`

Mint a token for the caller. The secret is in the answer and nowhere else.

Body: MintTokenBody

Status	Means	Body
201	Created	TokenMintedResponse
401	No token, or a token that is not valid
403	A machine operator cannot mint tokens
404	Not found
422	A token cannot carry more than the caller does

`DELETE /api/v1/tokens/{id}`

Revoke a token, instantly. An operator revokes their own; one who manages operators revokes anyone's.

Parameter	In	Type	About
`id`	path	string (uuid)

Status	Means	Body
204	Done, with no body
401	No token, or a token that is not valid
404	Not found

Types

MeResponse

Field	Type	About
`actor`	string	The audit actor string: the operator's email, or `api-token`.
`display_name`	string
`kind`	string	person \| machine
`machine`	boolean
`memberships`	array of MeMembership
`mfa`	boolean	Whether this operator has a TOTP authenticator enrolled.
`operator_id`	string (uuid)
`policies`	array of MePolicy
`suspended`	boolean
`token_id` (optional)	string (uuid) or null
`token_project` (optional)	string or null	A value means the token acts in this project and nowhere else.
`token_scopes` (optional)	array of string or null	null = a session bearer, which is never narrowed. A value means a minted token's snapshot of its role at mint time.
`via`	string	console \| token \| api-token

MfaConfirmBody

Field	Type	About
`code`	string

MfaEnrolResponse

Field	Type	About
`secret`	string	Base32, for manual entry. Shown once and never again.
`uri`	string	The otpauth:// URI the authenticator app scans.

SessionResponse

Field	Type	About
`created_at`	string
`current`	boolean	The session this very request arrived on.
`expires_at`	string
`id`	string (uuid)
`ip`	string
`kind`	string	console \| cli
`user_agent`	string

NotificationResponse

Field	Type	About
`created_at`	string
`id`	string (uuid)
`kind`	string	build.failed \| deployment.rolled \| deployment.refused \| deployment.auto_rollback \| probe.down \| quota.high \| package.published
`link` (optional)	string or null	The console path the notice opens, relative.
`params`	any	PII free: slugs, names of things, numbers.
`read`	boolean

UnreadCountResponse

The badge in the operator menu: global, never per project.

Field	Type	About
`unread`	integer

PermissionResponse

Field	Type	About
`group`	string
`hint`	string
`key`	string
`label`	string

AuditResponse

Field	Type	About
`action`	string	The permission that was asked for, or the verb of a self service write.
`actor`	string	The operator email, or `api-token` / `github-app` for a machine caller.
`at`	string
`environment` (optional)	string or null
`id`	integer
`ip`	string
`outcome`	string	allowed \| denied
`project` (optional)	string or null
`reason`	string	The deny reason of a refusal, empty when allowed.
`target`	string
`via`	string	console \| token \| api-token \| system

EnvironmentPolicyResponse

Field	Type	About
`allowed`	array of string
`environment`	string
`removed`	array of string	What this policy takes away from the role, for the console's muted line.
`role_id`	string (uuid)
`role_name`	string
`updated_at`	string

WritePolicyBody

Field	Type	About
`allowed`	array of string

MemberResponse

Field	Type	About
`display_name`	string
`email`	string
`kind`	string	person \| machine
`operator_id`	string (uuid)
`project` (optional)	string or null
`project_name` (optional)	string or null
`role_id`	string (uuid)
`role_name`	string
`role_slug`	string
`since`	string

WriteMembershipBody

Field	Type	About
`operator_id`	string (uuid)
`role_id`	string (uuid)

CandidateResponse

One operator the Add member form may offer: identity only, no memberships, no sessions, no MFA state, kind person | machine.

Field	Type	About
`display_name`	string
`email`	string
`id`	string (uuid)
`kind`	string

NotificationSettingResponse

One kind's two channels, with the label the section draws.

Field	Type	About
`email`	boolean
`in_app`	boolean
`kind`	string
`label` (optional)	string	Ignored on the way in: the label belongs to the API, not to the form.

WriteNotificationSettingsBody

Field	Type	About
`settings`	array of NotificationSettingResponse

RoleResponse

Field	Type	About
`description`	string
`display_name`	string
`fixed`	boolean
`id`	string (uuid)
`members`	integer
`permissions`	array of string	The console keys on `fixed`, not on this.
`project` (optional)	string or null
`slug`	string

WriteRoleBody

Field	Type	About
`description` (optional)	string
`display_name`	string
`permissions`	array of string
`project` (optional)	string or null	Ignored on PUT and on the project scoped routes, where the path decides: a role never moves.
`slug`	string

TokenResponse

Field	Type	About
`created_at`	string
`expires_at` (optional)	string or null
`id`	string (uuid)
`kind`	string	api \| cli \| mcp
`last_used` (optional)	string or null
`name`	string
`operator`	string	The operator's email, or the machine's handle.
`operator_id`	string (uuid)
`project` (optional)	string or null	null = the token acts wherever its operator may.
`revoked`	boolean
`role_id`	string (uuid)
`role_name`	string
`scopes`	array of string

MintTokenBody

Field	Type	About
`expires_in_days` (optional)	integer or null	Days until expiry. Omitted = `OPS_TOKEN_TTL_DAYS`, 0 = no expiry.
`kind` (optional)	string or null	api (default) \| cli \| mcp
`name`	string
`project` (optional)	string or null	null = the token acts wherever its operator may; a slug pins it.
`role_id`	string (uuid)

TokenMintedResponse

Field	Type	About
`secret`	string	The raw bearer, `opst_…`. Shown ONCE: it is never stored and cannot be read back, so a lost secret is a new token.
`token`	TokenResponse

MeMembership

Field	Type	About
`fixed`	boolean
`permissions`	array of string
`project` (optional)	string or null
`role_id`	string (uuid)
`role_name`	string
`role_slug`	string

MePolicy

Field	Type	About
`allowed`	array of string
`environment`	string
`project`	string
`role_id`	string (uuid)