User
Benutzer gehören zu einem Tenant und tragen Rollen, die festlegen, was sie tun dürfen. Öffentliche v2-Endpoints verwenden snake_case-Schlüssel und sind in der OpenAPI-Spezifikation dokumentiert; die wichtigsten Punkte finden Sie unten.
Endpoints
GET /api/v2/users— paginierte Liste der Tenant-Benutzer (ohne Service-Accounts).POST /api/v2/users— legt einen Benutzer an oder lädt eine Person per E-Mail ein, wenn die Personen ihr Profil selbst verwalten (siehe Einladungen). Die E-Mail-Adresse wird beim Anlegen gesetzt und kann nicht mehr geändert werden.PATCH /api/v2/users/{user_id}— JSON Merge Patch (RFC 7396). Felder weglassen, um sie unverändert zu lassen; ein Feld aufnullsetzen, um es zu leeren.lock_versionist optional: wenn angegeben, wird es gegen die gespeicherte Version geprüft (409bei Abweichung); wenn weggelassen, entfällt die Nebenläufigkeitsprüfung.
Payloads
Create (POST /api/v2/users)
{
"email": "bea@example.com",
"firstname": "Bea",
"lastname": "Smith",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"],
"phone_number": "+43123456789"
}
Antwort (created):
{
"id": "1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af",
"email": "bea@example.com",
"roles": ["dispatcher"],
"firstname": "Bea",
"lastname": "Smith",
"profile_status": "COMPLETE",
"created_at": "2024-01-15T10:30:00Z",
"status": "ACTIVE",
"is_profile_self_managed": false
}
Patch (PATCH /api/v2/users/{user_id})
Content-Type: application/merge-patch+json (application/json wird als Alias akzeptiert)
{
"lock_version": 3,
"firstname": "Bea Updated",
"phone_number": null
}
Hinweise:
- Die E-Mail-Adresse kann nach dem Anlegen nicht mehr geändert werden.
role_idsdarf niemals leer sein.firstnameundlastnamekönnen nicht geleert werden. Wois_profile_self_managedtrueist, kann nur die Person selbst ihren Namen und ihre Telefonnummer ändern (sonst422 users/profile-self-managed).
Einladungen
In Workspaces, in denen Personen ein Anmeldekonto für alle ihre Tourfold-Workspaces behalten, verwaltet
jede Person ihren Namen und ihre Telefonnummer selbst; ihre Benutzer tragen is_profile_self_managed: true.
Dort lädt POST /api/v2/users eine Person per E-Mail ein:
{
"email": "lena.huber@example.com",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"]
}
- Eine Person, die neu bei Tourfold ist, erhält eine Einladungs-E-Mail und setzt ein Passwort; eine
Person, die bereits ein Tourfold-Konto hat, erhält eine E-Mail, dass sie hinzugefügt wurde. In beiden
Fällen hat der Benutzer
profile_status: PENDINGund wederfirstname,lastnamenochphone_number(die Eigenschaften fehlen), bis sich die Person zum ersten Mal in diesem Workspace anmeldet; zeigen Sie stattdessen die E-Mail-Adresse an. Diese Anmeldung füllt das Profil und sendet einenuser.updated-Webhook mitprofile_status: COMPLETE. - Die Anfrage enthält weder
firstname,lastnamenochphone_number: nur die Person setzt sie. Eine Anfrage mit einem dieser Felder erhält422 users/profile-self-managedmit den Feldnamen indata.fields, und es wird kein Benutzer angelegt. Die Antwort verrät nicht, ob zu der E-Mail-Adresse bereits ein Konto bestand. POST /api/v2/users/{user_id}/resend-set-password-emailsendet die E-Mail erneut, solangecan_resend_set_password_emailtrueist.
Wo der Workspace die Profile seiner Personen verwaltet (is_profile_self_managed: false), sind
firstname und lastname erforderlich und phone_number ist optional, wie bisher. Ein leerer Name
erhält in jedem Workspace einen field-required-Eintrag („must not be blank“) neben allen anderen
Feldfehlern. Sind die übrigen Felder gültig, erhält ein fehlender oder auf null gesetzter Name
422 validation-failed mit einem field-required-Eintrag je fehlendem Namen.
Rollen
Listet die Rollen des aktuellen Tenants mit ihren aktivierten Grants auf:
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"]
}
]
}