Skip to content

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) ​

FieldTypeRequired
display_namestringNo
emailstringYes
usernamestringYes
json
{
  "display_name": "Alice Example",
  "email": "alice@example.test",
  "username": "alice"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3USER000000000000001",
  "status": "invited"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
422username or email already existsInvalid Request
500authentication service unavailableInternal 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 ​

ParameterDescription
userIDPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
422account is not invitedInvalid Request
500authentication service unavailableInternal 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 ​

ParameterDescription
userIDPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
422account is not invitedInvalid Request
500authentication service unavailableInternal Server Error