Invite User

Admin sends invitation email. User completes registration and sets their own password.

Purpose and Benefits

What is User Invitation?

User invitation allows administrators to invite new users to your platform. Unlike creating users directly, invitations let users set their own password during registration, providing a more secure and user-friendly onboarding experience.

Key Benefits

Benefit	Description
User-Controlled Security	Users set their own password during registration, ensuring they never share credentials
Pre-configured Access	Assign groups and roles before registration - automatically applied when user completes signup
Pre-filled Registration	User data (name, email, custom fields) is pre-filled, reducing registration friction
Trackable Onboarding	Monitor invitation status, track acceptance rates, and manage pending invitations
OAuth2 Compliance	Uses initiate_login_uri to ensure proper OAuth2 flow with client-side generated parameters (state, code_verifier for PKCE), enabling seamless login after registration
Email/SMS Templates	Customize invitation messages with branded templates and multiple languages

When to Use Invitations

• Team Onboarding: Invite new team members with pre-assigned roles and permissions
• Customer Invitations: Onboard customers to your platform with personalized invitations
• Secure Onboarding: When users should set their own passwords (better security practice)
• Bulk Invitations: Invite multiple users who will complete registration at their own pace
• Controlled Access: Pre-assign users to specific groups before they register

Quick Comparison

Aspect	Invite User	Create User
Password Set By	User (during registration)	Admin (set in request)
User Action Required	Registration + Login	Login only
User Status	Created only after registration	Created immediately
Use Case	Team onboarding, customer invitations	Automated provisioning, bulk imports

Prerequisites

Before inviting users:

-Field Settings](/guides/user-management/setup/field-settings) configured

• User Groups created (if needed)
• User Roles defined (if needed)
• App Settings configured

Invitation Flow

The following sequence diagram illustrates the complete invitation process from creation to user registration:

Flow Steps Explained

1. Admin Creates Invitation

   • Admin calls POST /useractions-srv/invitations with user details
   • invite_id is generated and stored with invitation data
   • System adds invite_id to the authorization URL as an extra parameter
   • API Reference: See Invite User API for request/response examples

2. System Generates Invitation Link

   • Link points to client's login page (initiate_login_uri) with invite_id and view_type=register as query parameters
   • Link is shortened with a 7-day lifetime

3. User Receives Email

   • User receives email/SMS with the shortened invitation link
   • Link contains invite_id and view_type=register

4. User Clicks Link

   • User is redirected to client's login page
   • Client creates OAuth2 parameters (state, code_verifier for PKCE, etc.) required for the OAuth flow
   • Client redirects to authz endpoint with invite_id, view_type=register, and OAuth2 parameters
   • Important: OAuth2 parameters must be created client-side to enable login after successful registration

5. Registration UI Loads

   • Authz redirects user to the registration UI with invite_id in the URL
   • Registration UI calls GET /useractions-srv/invitations/{inviteId} to retrieve invitation details
   • Pre-filled information (name, email, groups) is returned
   • API Reference: See Get Invitation API for response example

6. User Sees Registration Form

   • Registration form is displayed with pre-filled data from invitation
   • Form includes invite_id in the submission URL

7. User Registers

   • User submits registration via POST /useractions-srv/registration with invite_id provided as:
     • Query parameter: ?invite_id={inviteId} (most common)
     • Header: invite_id: {inviteId}
   • System retrieves invitation using invite_id (checks both query parameter and header)
   • User account is created and linked to the invitation
   • Groups and roles from invitation are automatically assigned
   • Invitation state changes to accepted
   • API Reference: See Register User API for request examples with invite_id

8. User Completes Login

   • After successful registration, OAuth2 parameters (state, code_verifier) created by the client allow the user to complete the login flow
   • User is automatically logged in and redirected to the application

Related: Register User

Important Invitation Fields

Field	Description	Required
email	Email address to send invitation	Yes (or mobile_number)
mobile_number	Mobile number for SMS invitation	Yes (or email)
given_name, family_name	User's name (pre-fills registration)	Optional
groups	Groups to assign after registration	Optional
client_id or client_name	App for registration redirect	Required
initiate_login_uri	Client's login page URL (required for OAuth2)	Required
invite_template_key	Custom email/SMS template	Optional (default: INVITE_USER)
lang	Language for invitation email	Optional (uses Accept-Language header)
customFields	Pre-filled custom field values	Optional
allow_same_email	Restrict registration to invited email	Optional

Important: initiate_login_uri is required because OAuth2 temporary parameters (like state, code_verifier for PKCE) must be created client-side. These parameters are essential for completing the user login flow after successful registration. Without them, the user cannot complete the OAuth2 authorization flow.

Technical Integration

Endpoint	Method	Description	Link
Invite User	POST	Create a new user invitation	POST /useractions-srv/invitations
Get Invitation	GET	Retrieve invitation details by invite ID	GET /useractions-srv/invitations/:inviteId
Update Invitation State	PATCH	Resend or change invitation state	PATCH /useractions-srv/invitations/:inviteId
Find Invitations	POST	Search invitations with filters	POST /useractions-srv/graph/invitations
Register User	POST	Register a new user (with invite_id)	POST /useractions-srv/registration

Important Details

Invitation Email Templates

The invitation email/SMS uses the INVITE_USER template by default, or a custom template if invite_template_key is provided.

Custom Template Keys

You can define your own template key (e.g., "CRM_INVITE"):

• Custom Template: Set invite_template_key in the request
• Template Must Exist: Template must be configured in your tenant's template service
• Template Group: "default"
• Template Type: EMAIL or SMS (based on medium)
• If Not Found: Returns error "invalid template key used to invite user"

Template Variables Available

• {{name}} - User's full name (given_name + family_name)
• {{invite_link}} - Registration URL (valid for 7 days, shortened)
• {{invited_by}} - Name of person who sent invitation
• {{account_name}} - Tenant/organization display name

Language/Locale

• Set via lang field in request body, or
• Accept-Language HTTP header (e.g., Accept-Language: de)

What the User Receives

• Personalized email/SMS with their name
• Clickable registration link
• Information about who invited them
• Account/organization name

Invitation States

State	Description	Actions
initiated	Invitation created	Can resend
reinitiated	Invitation resent	Can resend again
accepted	User registered	Account created
revoked	Cancelled by admin	Create new invitation
rejected	Rejected by user	Create new invitation

Change State: PATCH /useractions-srv/invitations/:inviteId

API Reference: Update Invitation State

Webhooks and Facts

When invitations are created, accepted, or reinitiated, fact events (webhooks) are sent with the invite_id:

• Event Type: INVITE_USER
• Object ID: The invite_id (unique invitation identifier)
• Webhook Attributes: ["_id"] (contains invite_id), or ["_id", "sub"] when accepted
• Use Case: Track invitation campaigns, monitor acceptance rates, integrate with external systems

The invite_id allows you to:

• Link webhook events to specific invitations
• Track which invitation triggered each event
• Monitor invitation lifecycle in external systems

Invitations vs Users in Search

Important: Invited users do not appear in user search results until they complete registration.

• Before Registration: User exists only as an invitation (searchable via /useractions-srv/graph/invitations)
• After Registration: User account is created and appears in user search (/user-srv/graph/users)
• Invitation States: Track invitation lifecycle separately from user accounts

Groups & Roles

Assigning Groups

• Assign Groups: Groups assigned during invitation
• Auto-Assignment: User automatically added to groups after registration
• User Status: User account created only after registration is completed

Required Roles

Operation	Required Roles
Invite User	admin, secondary_admin, user_invite

Field Configuration

System Fields

Stored in Identity object:

• given_name, family_name
• email, mobile_number
• username

Custom Fields

Stored at account level:

• Business-specific attributes
• Must be configured in Field Settings

Related: Account Structure

Admin Dashboard: Invite User

Required Roles: admin, secondary_admin, or user_invite

1. Navigate to Users > Invite User
2. Select Admin or User type
3. Enter email address
4. Configure groups and roles
5. Click Invite User

Result: User receives invitation email with registration link.

Related Topics

Topic	Description	Link
Create User	Admin sets password	Create User
Register User	Self-service registration	Register User
Account Structure	User data model	Account Structure
Update Account	Modify user profile	Update Account
User Groups	Access control	User Groups

Need Support?

Please contact us directly on our support page.