Set user roles from your backend

Filters

Feature

Organisation user roles

New

Set a role when you create a user

POST /v1/organisations/{organisationId}/users now accepts an optional role — Member, Admin, or Owner. Omit it and the user is created as a Member, as before.

{
  "email": "[email protected]",
  "name": "Alice Johnson",
  "role": "Owner"
}

This means you can provision an organisation and name its Owner in a single call, rather than creating the user and then changing their role. See Client integration.

Manage organisation users with an API key

These endpoints now accept an API key, in addition to a session token:

Endpoint	What it does
`POST /v1/users`	Add a user to the organisation in `x-dolfin-organisation-id`
`PATCH /v1/users/{id}/role`	Change a member’s role
`DELETE /v1/users/{id}`	Remove a member from the organisation

Your key can only reach organisations belonging to your client, and an organisation must always keep at least one Owner.

Changed

Granting a role is capped at your own

A caller can no longer grant a role above their own. An Admin holding a session token can add Members and Admins but not an Owner; a Member can add only Members. Attempting it returns:

{
  "code": "User.RoleAboveCaller",
  "status": 403,
  "detail": "You cannot assign or modify a role higher than your own."
}

An API key acts with your client’s authority over its own organisations, so it can grant any role, including Owner.

​New

​Set a role when you create a user

​Manage organisation users with an API key

​Changed

​Granting a role is capped at your own

New

Set a role when you create a user

Manage organisation users with an API key

Changed

Granting a role is capped at your own