Invite User
POST /v1/nodes/invite-user
Invites a user by email to a specific node with a designated role. The invited user receives an email with instructions to join.
Authorization Checks
This endpoint performs several authorization checks:
- Node hierarchy -- The API key's node must be a parent of (or the same as) the target node. You can only invite users to nodes you manage.
- Role exists -- The specified role must exist within the target node.
- Priority check -- The API key's priority must be higher than the target role's priority. You cannot assign roles with higher privilege than your own.
- User uniqueness -- The email must not already be registered in the target node.
Headers
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <token> |
Content-Type | Yes | application/json |
X-Target-Server | Yes | nodes |
Request Body
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
email | string | Yes | Valid email format | Email address of the user to invite |
role_id | string (UUID) | Yes | Valid UUID | Role to assign to the user |
node_id | string (UUID) | Yes | Valid UUID | Node to invite the user to |
{
"email": "john.doe@example.com",
"role_id": "bb0e8400-e29b-41d4-a716-446655440000",
"node_id": "660e8400-e29b-41d4-a716-446655440000"
}
Response
201 Created
User invited successfully. An invitation email is sent to the specified address.
400 Bad Request
Validation error (invalid email, missing fields).
401 Unauthorized
403 Forbidden
Not authorized to manage the target node, or insufficient priority for the target role.
{
"code": 0,
"domain": 0,
"message": "not authorized to manage this node"
}
409 Conflict
User already exists in the target node.