> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set user roles from your backend

> Create users at any role with your API key, and change or remove them programmatically.

<Update label="2026-08-07" tags={["Feature"]} description="Organisation user roles">
  ## New

  ### Set a role when you create a user

  [`POST /v1/organisations/{organisationId}/users`](/api-reference/endpoint/users/create-user) now accepts an optional `role` — `Member`, `Admin`, or `Owner`. Omit it and the user is created as a `Member`, as before.

  ```json theme={null}
  {
    "email": "alice@acmeplumbing.co.uk",
    "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](/guides/client-integration#step-2-create-users).

  ### 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`](/api-reference/endpoint/users/add-user-to-my-organisation)                    | Add a user to the organisation in `x-dolfin-organisation-id` |
  | [`PATCH /v1/users/{id}/role`](/api-reference/endpoint/users/update-user-role-in-my-organisation) | Change a member's role                                       |
  | [`DELETE /v1/users/{id}`](/api-reference/endpoint/users/remove-user-from-my-organisation)        | 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 `Member`s and `Admin`s but not an `Owner`; a `Member` can add only `Member`s. Attempting it returns:

  ```json theme={null}
  {
    "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`.
</Update>