Members & roles

Project members, invitations and roles — the Member and Role objects, the permission bitmask, and the endpoints for inviting, re-assigning and removing members and managing roles.

Every project member has exactly one role. A role is a named set of permissions, stored as an integer bitmask. The project owner is a member too but bypasses all permission checks, whatever their role.

New members join by invitation: inviting an existing Configo user by email sends them a notification. They become a member only when they accept it. Until then, the invitation is listed among the members with is_pending: true.

Field types follow the field notation.

Access

Every endpoint on this page requires both the projects and members OAuth scopes. The user must be a member of the project, and the owner's subscription must be active. Otherwise the endpoint returns 404 RES_NOT_FOUND.

Managing members and roles requires both can_edit_project and can_edit_members. Reading roles requires the same two permissions, because a role is the project's access map. Any member can list members.

Member Object

Member Structure

Example Member

{
  "uuid": "0198f0b2-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  "email": "[email protected]",
  "user_name": "Ivan Sidorov",
  "role_uuid": "0198e7a0-0000-7000-8000-0000000000a2",
  "role_name": "Manager",
  "permissions": 14293971053567,
  "is_pending": false,
  "created_at": "2026-07-02T08:00:00.000Z",
  "updated_at": "2026-07-02T08:00:00.000Z"
}

List Members

GET /api/v1/projects/{project.uuid}/members

Returns all members, oldest first, followed by pending invitations. Any member can call it.

Errors

Get Member

GET /api/v1/projects/{project.uuid}/members/{member.uuid}

Returns a single member, without is_pending. Pending invitations are not returned here. Any member can call it.

Errors

Invite Member

POST /api/v1/projects/{project.uuid}/members

Invites a registered Configo user. The user gets a notification and joins with the given role once they accept it. The owner's plan member limit is checked when the invitation is sent. Pending invitations do not count towards it.

Requires can_edit_project and can_edit_members.

JSON Params

Example Request

{
  "email": "[email protected]",
  "role_uuid": "0198e7a0-0000-7000-8000-0000000000a2"
}

Response

201 Created

{
  "user_uuid": "0198f0b2-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  "invited": true
}

Errors

Modify Member

PATCH /api/v1/projects/{project.uuid}/members/{member.uuid}

Changes the member's role. PUT on the same path behaves identically. You cannot change your own role.

Requires can_edit_project and can_edit_members.

JSON Params

Response

204 No Content

Errors

Remove Member

DELETE /api/v1/projects/{project.uuid}/members/{member.uuid}

Removes a member, or revokes a pending invitation for that user. Their orders, contacts and tasks stay in the project and keep them as the responsible member.

Leaving a project. A member can pass their own uuid to leave. This needs no permissions and works even when the owner's subscription has lapsed. The owner cannot leave or be removed.

Requires can_edit_project and can_edit_members, except when leaving.

Response

204 No Content

Errors

Role Object

Role Structure

Example Role

{
  "uuid": "0198e7a0-0000-7000-8000-0000000000a2",
  "name": "Manager",
  "permissions": 14293971053567,
  "order": 2,
  "created_at": "2026-06-26T10:00:00.000Z"
}

Permission bits

permissions is the sum (bitwise OR) of these values. The largest value fits in a JavaScript number without loss. Bits not listed are reserved, and a mask containing them is rejected with REQ_VALIDATION_FAILED.

For orders, contacts and tasks, the three view permissions are alternatives: a role normally has one of own/role/all. The widest one present applies.

A new project's Owner role has every bit above: 4291608416878591. Its Manager role has 14293971053567.

List Roles

GET /api/v1/projects/{project.uuid}/roles

Returns the project's roles, sorted by order.

Requires can_edit_project and can_edit_members.

Errors

Get Role

GET /api/v1/projects/{project.uuid}/roles/{role.uuid}

Returns a single role.

Requires can_edit_project and can_edit_members.

Errors

Same as List Roles, plus 404 RES_NOT_FOUND if the role does not exist.

Create Role

POST /api/v1/projects/{project.uuid}/roles

Creates a role at the end of the list.

Requires can_edit_project and can_edit_members.

JSON Params

Example Request

{
  "name": "Production",
  "permissions": 206158430208
}

That is can_view_warehouses + can_edit_warehouses.

Response

201 Created

{
  "uuid": "0199a8d3-0a1b-7c2d-8e3f-405162738495"
}

Errors

Modify Role

PATCH /api/v1/projects/{project.uuid}/roles/{role.uuid}

Updates any of name, permissions, order (integer ≥ 0). At least one must be present. A change of permissions applies to every member with this role immediately.

Requires can_edit_project and can_edit_members.

Response

204 No Content

Errors

Replace Role

PUT /api/v1/projects/{project.uuid}/roles/{role.uuid}

Same as Modify Role, but name, permissions and order are all required.

Delete Role

DELETE /api/v1/projects/{project.uuid}/roles/{role.uuid}

Deletes the role. Members who had it are left without a role and lose access to the project until they are given another one through Modify Member. Move them to another role first.

Requires can_edit_project and can_edit_members.

Response

204 No Content

Errors