Invite an existing user or new user to join an existing account.

Published on Jul 22, 2025

3 minute(s) read

Prev Next

Post

/sys/v1/users/invite

Invite an existing user or new user to join an existing account.

Security

HTTP

Type bearer

API Key: apiKeyAuth

Header parameter nameAuthorization

Body parameters

Expand All

object

account_role

Array

User's role(s) and state in an account.

User account flag or legacy user account role name or custom role id

OneOf

string

Valid values[ "STATEENABLED", "PENDINGINVITE" ]

string

Valid values[ "ACCOUNTADMINISTRATOR", "ACCOUNTMEMBER", "ACCOUNTAUDITOR" ]

string (uuid)

string

add_groups

object | null

property*

Array additionalProperties

User's role(s) in a group.

Legacy user group role name or custom role id

OneOf

string

Valid values[ "GROUPAUDITOR", "GROUPADMINISTRATOR" ]

string (uuid)

string

add_mfa_devices

Array of object (FidoAddDeviceRequest) | null

FIDO devices to add. Only one device can be added at present.

object

name

string Required

A user friendly name for the device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

attestationResult

object Required

string (byte)

type

string

https://www.w3.org/TR/webauthn-2/#enum-credentialType

This enum defines valid cred types.

Valid values[ "public-key" ]

response

object

clientDataJSON

string (byte) Required

getTransports

Array of object (AuthenticatorTransport) | null

Values obtained from AuthenticatorAttestationResponse.getTransports(). Webauthn spec recommends RP to store it and user them along with allowCredentials while authentication ceremony.

Hints by relying party on how client should communicate with the authenticator.

https://www.w3.org/TR/webauthn-2/#enum-transport

OneOf

string

Valid values[ "usb", "nfc", "ble", "internal" ]

string

attestationObject

string (byte) Required

get_client_extension_results

object

appidExclude

boolean | null

Response of appidExclude extension. See [AuthenticationExtensionsClientInputs::appid_exclude].

appid

boolean | null

Response of appid extension. See [AuthenticationExtensionsClientInputs::appid].

add_u2f_devices

Array of object (U2fAddDeviceRequest) | null

object

name

string Required

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

registrationData

string (byte) Required

clientData

string (byte) Required

version

string Required

del_groups

object | null

property*

Array additionalProperties

User's role(s) in a group.

Legacy user group role name or custom role id

OneOf

string

Valid values[ "GROUPAUDITOR", "GROUPADMINISTRATOR" ]

string (uuid)

string

del_mfa_devices

Array of object (MfaDelDeviceRequest) | null

Mfa devices to delete

object

name

string Required

Name of the FIDO device to delete.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

del_u2f_devices

Array of object (MfaDelDeviceRequest) | null

object

name

string Required

Name of the FIDO device to delete.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

description

string | null

enable

boolean | null

first_name

string | null

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

last_name

string | null

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

mod_groups

object | null

property*

Array additionalProperties

User's role(s) in a group.

Legacy user group role name or custom role id

OneOf

string

Valid values[ "GROUPAUDITOR", "GROUPADMINISTRATOR" ]

string (uuid)

string

rename_mfa_devices

Array of object (MfaRenameDeviceRequest) | null

Mfa devices to rename

object

old_name

string Required

Old name of FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

new_name

string Required

New name of FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

rename_u2f_devices

Array of object (MfaRenameDeviceRequest) | null

object

old_name

string Required

Old name of FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

new_name

string Required

New name of FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

user_email

string (email)

user_password

string

Responses

2XX

Success result

Expand All

object

account_role

Array

User's role(s) and state in an account.

User account flag or legacy user account role name or custom role id

OneOf

string

Valid values[ "STATEENABLED", "PENDINGINVITE" ]

string

Valid values[ "ACCOUNTADMINISTRATOR", "ACCOUNTMEMBER", "ACCOUNTAUDITOR" ]

string (uuid)

string

created_at

string

Pattern^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$

Example20170509T070912Z

dependent_services

Array of string | null

string

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

description

string | null

email_verified

boolean | null

explicit_groups

object | null

Explicit group assignments.

This is similar to groups field except that it does not include groups due to all-groups roles. Use this field to find out which group assignments can be changed using mod_groups and del_groups fields in user update API.

property*

Array additionalProperties

User's role(s) in a group.

Legacy user group role name or custom role id

OneOf

string

Valid values[ "GROUPAUDITOR", "GROUPADMINISTRATOR" ]

string (uuid)

string

first_name

string | null

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

groups

object | null

property*

Array additionalProperties

User's role(s) in a group.

Legacy user group role name or custom role id

OneOf

string

Valid values[ "GROUPAUDITOR", "GROUPADMINISTRATOR" ]

string (uuid)

string

has_account

boolean | null

has_password

boolean | null

last_logged_in_at

string

Pattern^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$

Example20170509T070912Z

last_name

string | null

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

mfa_devices

Array of object (MfaDevice)

Mfa devices registered with the user

object

name

string

Name given to the FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

type

string

Type of MFA device

Valid values[ "U2f", "Fido2" ]

origin

string | null

Origin of the FIDO device.

new_email

string (email)

self_provisioned

boolean | null

u2f_devices

Array of object (MfaDevice)

object

name

string

Name given to the FIDO device.

Max length4096

Pattern^[^\n]*[^\s\n][^\n]*$

type

string

Type of MFA device

Valid values[ "U2f", "Fido2" ]

origin

string | null

Origin of the FIDO device.

user_email

string (email)

user_id

string (uuid)

Was this article helpful?