Users & Roles API

Endpoints for managing users, their preset role, custom role assignment, and the role/permission catalogue itself.

Auth model in short: every user has one preset role (admin, devops, tech_lead, developer, viewer) plus an optional custom role referenced by roleId. Effective permissions are the union of the two, cached per-user for 60 s.


Preset roles

Role Typical usage
admin Full access. Can manage users, roles and every resource.
devops Cluster + infra ops. Users CRUD, deployments, secrets, backups.
tech_lead Project owner. Manages own projects, secrets and deployments.
developer Standard app dev. Reads projects, triggers deploys.
viewer Read-only. Dashboards, deployments, audit logs.

Every preset role is seeded on API boot; you cannot delete them. Custom roles sit alongside and can layer additional permissions.


User endpoints

GET /api/users

List every user.

Auth: devops or tech_lead

Response 200:

[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Admin",
    "email": "[email protected]",
    "role": "admin",
    "roleId": null,
    "gitlabId": null,
    "avatarUrl": null,
    "lastLogin": "2026-07-01T12:00:00.000Z",
    "isActive": true
  }
]

GET /api/users/me

The currently-authenticated user, including their custom role reference.

Auth: any authenticated user

Response 200:

{
  "id": "00000000-0000-0000-0000-000000000001",
  "name": "Admin",
  "email": "[email protected]",
  "role": "admin",
  "roleId": null,
  "roleRef": null,
  "lastLogin": "2026-07-01T12:00:00.000Z"
}

PATCH /api/users/me

Update your own display name or avatar. Cannot change your own role.

Auth: any authenticated user

Request Body:

{
  "name": "New Display Name",
  "avatarUrl": "https://cdn.example.com/me.png"
}

Response 200: Updated user object.


POST /api/users

Create a user directly (no email invite). Prefer POST /api/users/invite for onboarding flows.

Auth: devops

Request Body:

{
  "name": "Alice",
  "email": "[email protected]",
  "role": "developer",
  "gitlabId": null,
  "avatarUrl": null
}

Response 201: Created user object.

Error 400: Missing / invalid fields.


POST /api/users/invite

Invite a user by email. Idempotent-ish — returns 409 if the email already exists.

Auth: requires users.create permission

Request Body:

{
  "email": "[email protected]",
  "name": "Alice",
  "role": "developer",
  "roleId": "b3d5..."
}

role defaults to developer if omitted. roleId is optional (points at a custom role).

Response 201: Created user object.

Error 400: Email and name are required.

Error 409: User with this email already exists.


PUT /api/users/:id

Full update of a user record.

Auth: devops

Request Body: any of name, email, role, gitlabId, avatarUrl.

Response 200: Updated user.

Error 404: User not found.


PATCH /api/users/:id/role

Change a user's preset role and/or custom role. Clears their permission cache immediately so the change takes effect on the next request.

Auth: requires users.assign-role permission

Request Body:

{
  "role": "tech_lead",
  "roleId": null
}

Response 200: Updated user object.


DELETE /api/users/:id

Auth: devops

Deletes the user and all of their project memberships in one transaction. You cannot delete your own account (400). Audit-logged as user.deleted.

Response 200:

{ "success": true }

Error 404: User not found.


GET /api/users/:id/permissions

Resolve a user's effective permissions (preset ∪ custom). Useful for UI-level "can I do X" checks.

Auth: any authenticated user

Response 200:

{
  "userId": "…",
  "role": "developer",
  "roleId": null,
  "permissions": ["projects.list", "projects.read", "deployments.trigger"]
}

GET /api/users/init-demo

Bootstrap the demo users ([email protected], [email protected], [email protected], [email protected]). Runs automatically on first API boot; call it manually if the users table is empty for any reason.

Auth: None

Response 200:

{ "created": 4, "users": [ … ] }

Role endpoints

GET /api/roles

List custom roles.

Auth: requires users.list permission

Response 200:

[
  {
    "id": "…",
    "name": "release-manager",
    "description": "Can approve production deployments",
    "permissions": ["deployments.approve"],
    "isSystem": false,
    "isActive": true
  }
]

GET /api/roles/:id

Get one custom role.

Auth: requires users.list permission

Response 200: The role object.

Error 404: Role not found.


POST /api/roles

Create a custom role.

Auth: requires users.create permission

Request Body:

{
  "name": "release-manager",
  "description": "Approves prod deploys",
  "permissions": ["deployments.approve", "deployments.read"]
}

Permission strings are validated against the catalogue served by GET /api/permissions. Any unknown string is rejected with 400.

Response 201: Created role.


PUT /api/roles/:id

Update a custom role.

Auth: requires users.update permission

Request Body: any of name, description, permissions, isActive.

Response 200: Updated role.

Error 403: Cannot modify system role — set on isSystem: true presets.


DELETE /api/roles/:id

Auth: requires users.delete permission

Response 200:

{ "success": true }

Error 403: Cannot delete system role.


POST /api/roles/:id/permissions/validate

Dry-run a permission set against the catalogue. Useful before saving.

Auth: requires users.update permission

Request Body:

{
  "permissions": ["deployments.approve", "not.a.real.permission"]
}

Response 200:

{
  "valid": false,
  "unknown": ["not.a.real.permission"]
}

Permission catalogue

GET /api/permissions

The full list of permission strings recognised by the platform, grouped by resource. Use this to power a permission-picker UI.

Auth: requires users.list permission

Response 200:

{
  "users":       ["users.list", "users.create", "users.update", "users.delete", "users.assign-role"],
  "projects":    ["projects.list", "projects.read", "projects.create", "projects.update", "projects.delete"],
  "deployments": ["deployments.trigger", "deployments.approve", "deployments.read"],
  "secrets":     ["secrets.read", "secrets.write", "secrets.rotate"],
  "audit":       ["audit.read"]
}

The list is source-of-truth for role validation — no permission accepted by POST /api/roles is ever outside this set.