curl --request POST \
--url https://api.comstruct.com/v1/projects/user-assignments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"email": "jane.doe@example.com",
"roles": [
"MANAGER"
],
"projects": [
{
"project_number": "PRJ-0001"
}
]
}
'{
"success": true,
"status": "ASSIGNED",
"email": "jane.doe@example.com",
"role_ids": [
"44444444-4444-4444-8444-444444444444"
],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
],
"region_ids": []
}Assign users
Erforderliche Berechtigungen: projects:write, users:read, roles:read
Weist einer E-Mail eine oder mehrere mandantenweite Rollen zu und vergibt optional Mitgliedschaften auf Projekten und/oder Projektregionen. Der API-Schlüssel muss ein reiner Kunden-Schlüssel sein.
Bestehender Benutzer (status: ASSIGNED): Die E-Mail gehört bereits zu einem Benutzer des Mandanten (Vergleich ohne Groß-/Kleinschreibung). Alle angegebenen Rollen werden mandantenweit hinzugefügt; bereits vorhandene Rollen bleiben bestehen. Jede Projektmitgliedschaft verwendet die erste Rolle als projektbezogene Rolle und ersetzt bei Wiederholung diese Rolle. Regionsmitgliedschaften werden angelegt; bestehende Regionszeilen bleiben unverändert. projects und regions dürfen entfallen.
Unbekannte E-Mail (status: INVITED): Es wird mindestens ein Projekt oder eine Region benötigt. Pro Projekt wird eine ausstehende Einladung mit der ersten Rolle gespeichert, pro Region eine Einladung ohne Rolle. Weitere Rollen werden geprüft und in role_ids zurückgegeben. Mandantenweit gespeichert werden sie, sobald die E-Mail zu einem Benutzer gehört. Wiederholen Sie die Anfrage danach, um alle mandantenweiten Rollen zu setzen.
Adressierung: Jeder Projekteintrag enthält genau eines von project_number oder external_id. project_number ist nur je Buchungskreis eindeutig; ist sie im Mandanten mehrfach vergeben, antwortet die API mit HTTP 409 — verwenden Sie dann external_id. Regionen werden über region_number adressiert.
Upsert: Eine Wiederholung aktualisiert die bestehenden Zeilen. Ausgelassene Projekte, Regionen und Rollen bleiben unverändert. Alle Schreibvorgänge einer Anfrage laufen in einer Mutation und werden gemeinsam übernommen oder gemeinsam verworfen.
Leerzeichen an email, Rollentiteln und Kennungen werden entfernt. Rollentitel müssen exakt einer bestehenden Rolle des Mandanten entsprechen.
curl --request POST \
--url https://api.comstruct.com/v1/projects/user-assignments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"email": "jane.doe@example.com",
"roles": [
"MANAGER"
],
"projects": [
{
"project_number": "PRJ-0001"
}
]
}
'{
"success": true,
"status": "ASSIGNED",
"email": "jane.doe@example.com",
"role_ids": [
"44444444-4444-4444-8444-444444444444"
],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
],
"region_ids": []
}Overview
Assigns tenant-wide roles to an email and optionally grants project and region memberships. Repeating the request updates the existing rows. Assignments left out of the request stay as they are. The API key must be a customer API key.Permissions
| Scope | Description |
|---|---|
projects:write | Create and update projects |
users:read | Read user data |
roles:read | Read role data |
Behavior
- Role titles must match an existing tenant role exactly. The first role is the project-scoped role on every membership and every project invite.
- When the email already belongs to a tenant user, every listed role is added tenant-wide (
ASSIGNED). Roles, projects, and regions omitted from the request stay as they are. Sending the request again replaces the project-scoped role with the first role of the new request. - When the email is unknown,
projectsorregionsis required (INVITED). The project invite stores the first role; region invites carry no role. Further roles are validated and returned inrole_ids. Send the request again after the user exists to apply every tenant-wide role. project_numberis unique per legal entity. If more than one project in the tenant uses it, the API responds with 409; useexternal_id.- Each project entry contains exactly one of
project_numberorexternal_id. The same project or region must not appear twice, including when two identifiers resolve to the same target.
Response codes
| Code | Description |
|---|---|
201 | Assignment or invites stored |
400 | Invalid request |
401 | Unauthorized |
403 | Missing permission or not a customer API key |
404 | Project, region, or role not found |
409 | project_number is ambiguous in the tenant |
500 | Assignment or invites could not be stored |
Authorizations
API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer Success Manager, um einen API-Schlüssel zu erhalten.
Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die erforderlichen Scopes werden pro Endpunkt angezeigt.
Body
E-Mail-Adresse, der die Rollen und Mitgliedschaften zugewiesen werden.
"jane.doe@example.com"
Titel der mandantenweiten Rollen. Mindestens eine, ohne Duplikate. Jede Rolle muss im Mandanten existieren. Bei Projekten wird die erste Rolle als projektbezogene Rolle verwendet.
1["MANAGER", "CONTROLLER"]
Optionale Projekte. Jeder Eintrag enthält genau eines von project_number oder external_id.
Dasselbe Projekt darf nicht zweimal vorkommen. Für unbekannte E-Mails ist mindestens
ein Projekt oder eine Region erforderlich.
Show child attributes
Show child attributes
Optionale Projektregionen, adressiert über region_number. Duplikate werden abgelehnt.
Bestehende Benutzer erhalten die Mitgliedschaft sofort; unbekannte E-Mails eine ausstehende Einladung.
Show child attributes
Show child attributes
Response
Zuweisung oder Einladungen gespeichert
Ob die Zuweisung gespeichert wurde
true
ASSIGNED, wenn die E-Mail bereits zu einem Benutzer des Mandanten gehört.
INVITED, wenn stattdessen ausstehende Projekt- und/oder Regionseinladungen gespeichert wurden.
ASSIGNED, INVITED "ASSIGNED"
E-Mail, für die die Zuweisung gespeichert wurde
"jane.doe@example.com"
UUIDs der aufgelösten mandantenweiten Rollen, in der Reihenfolge der Anfrage
["44444444-4444-4444-8444-444444444444"]
UUIDs der aufgelösten Projekte. Leer, wenn nur Rollen und/oder Regionen zugewiesen wurden.
["33333333-3333-4333-8333-333333333333"]
UUIDs der aufgelösten Projektregionen. Leer, wenn keine Regionen angefragt wurden.
["55555555-5555-4555-8555-555555555555"]