PRprimitive
Roles and members

Create a custom role

A role nobody can use to gain access they do not hold: its permissions and mail scope must be within the author's own. mail_scope is "org" (the default) or { addresses, domains, depth }; a scope that names mailboxes must state its depth (metadata, content or raw), otherwise 400 validation_error with details.reason depth_required; any other value is refused with 400 validation_error. Its mail scope names no other member's personal mailbox: otherwise 403 grant_forbidden with details.reason personal_mailbox_member_only. Person only: a dashboard session, or the person's own OAuth or CLI token with a session step-up of purpose roles.write (the person confirms at the step_up_url a 403 step_up_required answer carries, which names this client, then send the token in the Primitive-Step-Up header; the token works only with the client it was confirmed for). Needs roles:assign. API keys are refused.

post/roles

Request

  • Base URL
    https://api.primitive.dev/v1
  • URL
    https://api.primitive.dev/v1/roles
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.

Request body

namestring required
descriptionstring nullable
permissionsstring[] required

Response

Create a custom role

successtrue required

Changes

No operation changes recorded.