Custom roles

Every person in an organization holds one of the three predefined roles: owner, admin or member. A custom role is a named set of permissions added on top of one of them, so one person can hold exactly the one thing their job needs without becoming an admin. A custom role is a set of the same permission names an API key holds, and it is assigned to a person or to a brand group.

What a request may do

The effective permissions of a request are the union of the predefined role and every custom role the person holds, directly or through a group. Nothing is cached: the roles are read with the session on every request, so a role added or removed takes effect on the next call, not at the next sign in.

curl -s -X POST https://api.162-55-213-24.sslip.io/v0/roles \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support lead", "description": "Reads the team screen", "permissions": ["member_read"]}'

What a request can see

A custom role grants permissions, never visibility. What a person can open is decided by the grants on an inbox or on a domain, and a role does not touch them: a role listing message_read for somebody with no grant answers 200 with an empty list, not somebody else's mail. This is the same intersection a scoped API key is subject to, and it holds by construction rather than by a check somebody can forget.

Assigning to a person or to a group

A PUT replaces the whole set for one subject, so the request says what the person should hold rather than what to add: a role left out of role_ids is revoked. Both halves are audited, as role.assign and role.revoke.

# One person
curl -s -X PUT https://api.162-55-213-24.sslip.io/v0/members/USER_ID/roles \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["ROLE_ID"]}'

# One brand group
curl -s -X PUT https://api.162-55-213-24.sslip.io/v0/groups/GROUP_ID/roles \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["ROLE_ID"]}'

A group is a brand. Its members are the people who can already see mail in it: those holding a grant on one of its domains or on one of its inboxes. Membership is read from the grants rather than copied into the assignment, so granting somebody a domain of the group is what makes them a member, and withdrawing the grant takes the role away with it. Deleting the group, deleting the role, or removing the person all revoke the assignments in the same transaction, and each is audited with the count.

Sensitive permissions are never implicit

data_delete and message_release are not effects of full access, and a custom role is not a way around that: a role that lists one of them can only be created or assigned by somebody who holds it too. The refusal is 403 permission_escalation, the same code a key gets when it tries to issue a wider key. In practice an owner builds the erasing role and hands it out; an admin cannot.

Errors

Endpoints