Appearance
Invitations API Reference
POST /invitations/
Create an invitation
Use from an administrator provisioning workflow to create an invited user and send a one-time invitation token. Username and email must be unique; the plaintext token is emitted only through notification delivery.
Required permission — iam:users:any
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| string | Yes | |
| username | string | Yes |
json
{
"display_name": "Alice Example",
"email": "alice@example.test",
"username": "alice"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3USER000000000000001",
"status": "invited"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 422 | username or email already exists | Invalid Request |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /invitations/{userID}
Cancel an invitation
Use when an invitation must be withdrawn before acceptance. The target must remain invited; cancellation deletes the user and cascaded records.
Required permission — iam:users:any
Path parameters
| Parameter | Description |
|---|---|
| userID | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 422 | account is not invited | Invalid Request |
| 500 | authentication service unavailable | Internal Server Error |
POST /invitations/{userID}/resend
Resend an invitation
Use when an invited user did not receive the original message. The previous invitation token is invalidated and a fresh seven-day token is emitted through notifications.
Required permission — iam:users:any
Path parameters
| Parameter | Description |
|---|---|
| userID | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 422 | account is not invited | Invalid Request |
| 500 | authentication service unavailable | Internal Server Error |