Roles API

Roles and their assignment live under /api/roles, any active license, admin only (403 otherwise). Errors are JSON with error and code.

Routes

Roles

{ "id": "…", "name": "Auditors", "description": "Reads the audit", "is_system": false,
  "permissions": ["audit:read"], "idp_groups": ["audit-team"], "member_count": 3, "created_by": "admin@example.com" }

POST /api/roles
{ "name": "Auditors", "description": "Reads the audit", "permissions": ["audit:read"], "idpGroups": ["audit-team"] }

PUT /api/roles/:id
{ "permissions": ["section:governance", "section:schema"] }

PUT /api/roles/user/:userId
{ "roleIds": ["…"] }

• name is required, trimmed, up to 100 characters, and unique in any letter case; it cannot be the name of a built-in role (admin, release_manager, approver, user).
• description is up to 500 characters.
• permissions holds keys from the catalog: the sections section:configuration, section:change, section:schema, section:governance, section:admin and section:overview, and audit:read, which lets the holder read and export the audit trail. Only the admin role can include section:admin, and the admin role always has every section.
• idpGroups is up to 50 group names of up to 200 characters each, for custom roles only. Repeated values are saved once.
• roleIds may name custom roles only; a user’s built-in role is changed with PUT /api/db-devops/users/:id.

Sections on other routes

A non-admin’s POST, PUT, PATCH and DELETE requests need the section the route belongs to in one of their roles: Configuration for environments, groupings, DB DevOps connections, Repo Sources and object consumers; Change Management for scripts, releases, approvals, executions, deployments, decision snapshots and shadow runs; Schema for schema operations, seed data, lint and preflight; Governance for compliance rules and AI agent runs. Reads are not refused.

403 { "error": "Your roles do not include Change Management, so you cannot make changes there. Ask an admin to add it to one of your roles.", "code": "SECTION_REQUIRED" }

Audit

Changes are recorded under the signed-in admin as CREATE_ROLE, UPDATE_ROLE (old and new values of what changed, with sections_added, sections_removed, idp_groups_added and idp_groups_removed), DELETE_ROLE (what the role granted and its members) and ASSIGN_ROLES (the user’s email and the roles added and removed).

Error codes