Roles

A Role is a named bundle of authority within one group. Roles carry a priority (higher = more authority), an optional color, a flag indicating whether they should be auto-assigned to new members, and a list of permission keys (populated via the grant / revoke routes documented below).

The group-scoped routes (POST /v1/groups/:id/roles and GET /v1/groups/:id/roles) live on this page; so do the by-id routes (GET /v1/roles/:id, PATCH /v1/roles/:id, DELETE /v1/roles/:id) and the permission-management routes (POST /v1/roles/:id/permissions, DELETE /v1/roles/:id/permissions/:permission).

Wire format

Role is the shape returned by every endpoint that emits it. Timestamps are ISO 8601 strings.

POST /v1/groups/:id/roles

Creates a new role inside the named group. Writes a role.created audit entry in the same transaction.

Request

{
  "name": "Officer",
  "priority": 80,
  "color": "#ff5050",
  "isDefault": false
}

permissions is intentionally not part of the create body; the grant route (POST /v1/roles/:id/permissions, documented below) is the dedicated path for adding permission keys.

Response

201 Created with a Role body. permissions is always [] on a freshly created role.

Audit log

One role.created entry, written in the same transaction:

{
  "groupId": "<groupId>",
  "actorUserId": null,
  "action": "role.created",
  "targetId": "<roleId>",
  "payload": {
    "name": "Officer",
    "priority": 80,
    "color": "#ff5050",
    "isDefault": false
  }
}

Errors

GET /v1/groups/:id/roles

Lists every role in a group. Returns a bare array (no pagination wrapper); roles are conventionally a small list (10s, not 1000s).

Path parameters

Response

200 OK with a Role[] body. Items are ordered by priority desc with id desc as a tiebreaker, so the highest-authority roles appear first. Permissions are batch-loaded for the page.

Errors

GET /v1/roles/:id

Fetches a single role by Role.id. Scoped to the calling game (a role whose group belongs to a different game returns 404 to avoid leaking existence). A soft-deleted group also 404s.

Response

200 OK with a Role body.

Errors

PATCH /v1/roles/:id

Updates one or more fields on an existing role. The body is partial: any subset of { name, priority, color, isDefault }. Empty body returns 400.

Each field is diffed per-field against the stored row. Only fields whose new value differs from stored go into the update statement and the audit payload. A no-op PATCH (every supplied value equals the stored one) skips the DB write entirely, returns the unchanged role, and writes no audit entry.

Request

{
  "priority": 90,
  "color": null
}

Response

200 OK with the updated Role body. permissions is loaded fresh.

Audit log

One role.updated entry per non-noop PATCH, with payload: { before, after } containing only the changed fields:

{
  "action": "role.updated",
  "targetId": "<roleId>",
  "payload": {
    "before": { "priority": 80, "color": "#ff5050" },
    "after": { "priority": 90, "color": null }
  }
}

Errors

DELETE /v1/roles/:id

Hard-deletes a role. Roles do not have a soft-delete window.

If any MemberRole rows reference the role, the request returns 409 role_has_members and the role is preserved. The caller must reassign affected members (or remove the assignment) before deleting.

On success, writes a role.deleted audit entry containing the deleted row’s snapshot:

{
  "action": "role.deleted",
  "targetId": "<roleId>",
  "payload": {
    "name": "Officer",
    "priority": 80,
    "color": "#ff5050",
    "isDefault": false
  }
}

Response

204 No Content on success.

Errors

POST /v1/roles/:id/permissions

Grants a permission key to a role. The route is idempotent: granting a permission the role already has returns the unchanged role with no audit entry and no DB write.

The first time a permission key is granted on a given game, it is auto-registered into PermissionDef (the per-game catalog of “known keys” the dashboard and SDK validators consult). Subsequent grants of the same key reuse the existing PermissionDef row; revoking the key later does not remove the def.

Request

{ "permission": "invite_member" }

Response

200 OK with the updated Role body. permissions reflects the post-state and is sorted by key.

Audit log

One permission.granted entry per non-noop grant:

{
  "action": "permission.granted",
  "targetId": "<roleId>",
  "payload": {
    "roleId": "<roleId>",
    "permission": "invite_member"
  }
}

Errors

DELETE /v1/roles/:id/permissions/:permission

Revokes a permission key from a role. The route is idempotent: revoking a permission the role does not have returns the unchanged role with no audit entry. The PermissionDef registry is preserved (revoke does not “forget” the key for the game).

Path parameters

Response

200 OK with the updated Role body. permissions reflects the post-state.

Audit log

One permission.revoked entry per non-noop revoke:

{
  "action": "permission.revoked",
  "targetId": "<roleId>",
  "payload": {
    "roleId": "<roleId>",
    "permission": "invite_member"
  }
}

Errors