Remove a capability grant from a user (admin)

DELETE

/admin/users/{ref}/grants/{capability}

• Local development behind nginx (port 8088 by default)

Pass team_id query param to scope to a team-scoped grant; omit for the global grant. Returns 404 when no matching grant exists (composite key, not by ID — there is no ID).

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

capability

required

string

Query Parameters

team_id

string format: uuid

Responses

204

Grant removed.

400

Grant removal refused — would leave the system with zero users holding system.admin (last-admin invariant guard). Applies to global system.admin grants only.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed