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

Throughout the invitation lifecycle, cidaas emits fact events that are delivered as webhooks. Three events are relevant to the invite-and-register flow:

Event Type	Triggered When	Object Type	Object ID	Webhook Attributes
INVITE_USER	An invitation is sent (POST /useractions-srv/invitations when the user is actually invited) or resent (PATCH .../:inviteId with state reinitiated)	userinvitations	invite_id	["_id"]
INVITE_ACCEPTED	The invited user completes registration with a valid invite_id, moving the invitation to accepted	userinvitations	invite_id	["_id", "sub"]
ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY	A new user account is created with a cidaas (local) identity during registration	users	sub	["provider", "requestId", "sub"]

INVITE_USER

• When: Emitted when an invitation is successfully sent. On PATCH .../:inviteId, it is also emitted when the state is set to reinitiated (resend) and accepted. It is not emitted if the invitation is not actually sent (for example, when the user already exists).
• Payload: objectType is userinvitations, objectId is the invite_id, newValue carries the full invitation, and url points to {publicURL}/users-webapp?inviteId={invite_id}.
• Webhook attributes: ["_id"] (the invite id). On the PATCH "accepted" path, attributes are ["_id", "sub"].

INVITE_ACCEPTED

• When: Emitted during registration (POST /useractions-srv/registration) when the request carries a valid invite_id. After the account is created, the invitation is updated to accepted (valid=false, acceptedTime set) and this fact is stored asynchronously.
• Payload: objectType is userinvitations, objectId is the invite_id, with both oldValue (before acceptance) and newValue (after acceptance) included.
• Webhook attributes: ["_id", "sub"] — lets you correlate the invitation with the newly created user.

ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY

• When: Emitted on successful registration when a new account is created with a cidaas (local) identity. This is the default account-creation event. Related variants are emitted for other paths: ACCOUNT_CREATED_WITH_SOCIAL_IDENTITY (new account via social login), and ACCOUNT_CIDAASIDENTITY_ADDED / ACCOUNT_SOCIALIDENTITY_ADDED (identity added to an existing account via deduplication/merge).
• Payload: objectType is users, objectId is the user's sub, and newValue is the register request with password removed (passwords are never persisted in facts).
• Webhook attributes: ["provider", "requestId", "sub"].

Use Cases

• Track invitation campaigns, monitor acceptance rates, and integrate with external systems.
• Link webhook events to specific invitations via invite_id and to the resulting user via sub.
• Monitor the full invitation-to-account lifecycle in external systems.

note

Facts are stored on a best-effort, asynchronous basis. If fact storage fails, the underlying API call still succeeds — so webhook delivery is not guaranteed transactionally with the user action. INVITE_USER and INVITE_ACCEPTED are webhook-only (not surfaced in changelog or user-activity), whereas ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY also feeds changelog and user activity. Invitation facts are retained for 365 days.

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

info

Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].