Skip to main content

User

Users belong to a tenant and carry roles that define what they can do. Public v2 endpoints use snake_case keys and are documented in the OpenAPI spec; highlights below.

Endpoints​

  • GET /api/v2/users — paginated list of tenant users (excluding service accounts).
  • POST /api/v2/users — create a user. Email is set on creation and cannot be changed.
  • PUT /api/v2/users/{user_id} — full replacement (all writable fields required).
  • PATCH /api/v2/users/{user_id} — JSON Merge Patch (RFC 7396). Omit fields to keep them unchanged; set a field to null to clear it. lock_version is optional: when provided it is validated against the stored version (409 on mismatch); when omitted the concurrency check is skipped.

Payloads​

Create (POST /api/v2/users)​

{
  "email": "bea@example.com",
  "firstname": "Bea",
  "lastname": "Smith",
  "role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"],
  "phone_number": "+43123456789",
  "external_id": "crm-1234"
}

Response (created):

{
  "id": "1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af",
  "email": "bea@example.com",
  "roles": ["OWNER", "DISPATCHER"],
  "firstname": "Bea",
  "lastname": "Smith",
  "created_at": "2024-01-15T10:30:00Z",
  "status": "ACTIVE"
}

Replace (PUT /api/v2/users/{user_id})​

{
  "firstname": "Bea",
  "lastname": "Smith",
  "phone_number": "+43123456789",
  "external_id": "crm-1234",
  "role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"],
  "lock_version": 3
}

Patch (PATCH /api/v2/users/{user_id})​

Content-Type: application/merge-patch+json (application/json is accepted as an alias)

{
  "lock_version": 3,
  "firstname": "Bea Updated",
  "phone_number": null
}

Notes:

  • Email cannot be changed after creation.
  • role_ids must never be empty; supply branch_group_id when roles are branch-scoped or when a user has multiple branch groups.

Roles​

List roles for the current tenant with their enabled grants:

GET /api/v2/roles
{
  "items": [
    {
      "id": "4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab",
      "name": "dispatcher",
      "role_type": "DISPATCHER",
      "grants": ["getUsers", "updateUser"]
    },
    {
      "id": "9f3b8e71-766f-4d5d-b9b4-8d57b92a9d52",
      "name": "driver",
      "role_type": "DRIVER",
      "grants": ["getUsers"]
    }
  ]
}