Roles

Create Role

Define a new role. It grants nobody anything until it is assigned.

Two of the app's own guards run inside the handler and are not duplicated here: _assert_can_grant_permissions refuses a permission the CALLER does not hold, and _require_teams_manage refuses manages_role_slugs without teams:manage. Both reach the caller as a 403 with the app's own message.

This is write rather than destructive on purpose: a brand-new role is held by no one, so creating it changes nobody's access. Editing one does - which is why PUT /roles/{role_id} is tiered differently.

post/roles

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/roles
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

namestring required
slugstring required
descriptionstring nullable
permissionsstring[]
manages_role_slugsstring[] nullable

Response

Successful Response

dataOrgPayload required

An open envelope for a single role, team, member or account record.

Open on purpose. The app's own response models on this surface grow with the product - RoleResponse gained rep_limits and manages_role_slugs, TeamResponse gained channel counts and a campaign count - and a pinned mirror would SILENTLY DROP whatever it had not caught up on. A dropped permission in a role read is the worst possible kind of stale: it reads as "they do not have it".

Changes

No recorded changes to this operation across all 3 revisions of this API.