Create User

Admin creates user with preset password. User receives login link via email.

Purpose and Benefits

What is User Creation?

User creation allows administrators to directly create user accounts in cidaas with admin-set passwords. Unlike invitations, created users are immediately active and searchable in the system, making this ideal for automated provisioning and bulk imports.

Key Benefits

Benefit	Description
Immediate Activation	User account is created and searchable immediately - no registration step required
Admin Control	Admin sets initial password, enabling automated provisioning and bulk imports
Backend Automation	Perfect for system-to-system integration and bulk user imports
Client login page	initiate_login_uri sends the user to your app login page to start OAuth2 with fresh state, nonce, and code_verifier (PKCE)
Email/SMS Templates	USER_CREATED and USER_CREATED_VERIFY; initiate_login_uri is the target for {{login_link}} in USER_CREATED
Instant Access	User can login immediately with provided credentials
Password Security	Option to force password change on first login (need_reset_password) for enhanced security

When to Use User Creation

• Backend Automation: Import users from external systems (HR, CRM, etc.)
• Bulk Provisioning: Create multiple users programmatically
• Automated Onboarding: System-generated accounts for new employees
• Migration: Import existing user databases
• Admin-Managed Accounts: When admin needs to control initial passwords

Quick Comparison

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

Prerequisites

Before creating users:

• Field Settings configured
• User Groups created (if needed)
• User Roles defined (if needed)
• App Settings configured
• initiate_login_uri configured in app settings (recommended for OAuth2 compliance)

Conditional Required Fields

When notify_user is enabled (notify_user: true, which is the default setting), cidaas triggers automated welcome notification delivery (via Email or SMS) and login-link generation. In this mode, the endpoint mandates OAuth2 authorization context to construct valid authentication entry points.

Parameter Validation Matrix

Parameter	Status when notify_user=true	Status when notify_user=false	Description & Validation Rules
client_id	Required	Optional	Unique application client ID. Must correspond to a valid registered client in the tenant. If omitted when notify_user=true, the API returns HTTP 400 (AUTH10002).
response_type	Required	Optional	OAuth2 response type (code, token, id_token). Must be enabled in the application's configured response_types. Defaults to code if configured on the client. If missing or invalid when notify_user=true, returns HTTP 400 (AUTH10002).
redirect_uri	Required	Optional	Target redirect URL for authentication redirect. Must strictly match one of the registered redirect_uris in the application configuration.
initiate_login_uri	Recommended	Optional	Client application login page URL configured in App Settings. When provided, {{login_link}} in USER_CREATED template directly points to this URL to initiate client-side PKCE flow.

Note on notify_user Behavior:

• notify_user: false → User is created without generating a login link (additional OAuth parameters like client_id, redirect_uri, response_type are not required).
• notify_user: true → Login link is generated, so additional OAuth parameters (client_id, redirect_uri, response_type) are required.

Warning: If notify_user is set to true (or omitted) and any of client_id, response_type, or redirect_uri are missing, the API execution will fail with error code AUTH10002 (invalid_request: request is missing a required parameter, response_type is missing).

User Creation Flow

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

Flow Steps Explained

1. Admin Creates User

   • Admin calls POST /users-srv/user/create/byadmin with user data and password
   • API Reference: See Create User API for request examples

2. User Account Created

   • User account is created immediately with sub (unique identifier)
   • User is immediately searchable in user search APIs
   • Groups and roles are assigned during creation
   • If need_reset_password: true, password reset is configured for first login

3. Login Link Generation & Dependency Chain (when notify_user is true)

   • Dependency Check: cidaas verifies the presence of client_id, response_type, and redirect_uri. If any required OAuth field is absent, creation halts and returns AUTH10002.
   • Link Resolution Priority:
     1. Initiate Login URI: If initiate_login_uri is passed in the request or configured in App Settings, cidaas uses this exact URI as the target for {{login_link}} in the USER_CREATED notification.
     2. Fallback Authorization URL: If initiate_login_uri is not configured, cidaas dynamically constructs a authorization URL formatted as: https://{tenant}/authz-srv/authz?client_id={client_id}&redirect_uri={redirect_uri}&response_type={response_type}
   • Admin Special Handling: Users assigned to CIDAAS_ADMINS group receive {tenant}/admin-ui as the login link in email.
   • Unverified Email Handling: If an email notification is triggered (primaryType: email) and email_verified is false, USER_CREATED_VERIFY template is selected, inserting a verification URL into {{verify_link}}.

4. Notification Sent

   • Channel is determined by primaryType (email, sms, or username; defaults to email when the user has an email address)
   • USER_CREATED (email with email_verified: true, or SMS): {{login_link}} targets initiate_login_uri or a built authz URL; includes password
   • USER_CREATED_VERIFY (email with email_verified: false): includes {{verify_link}} for account verification
   • Template variables: {{name}}, {{login_link}} or {{verify_link}}, {{password}}, {{account_name}}

5. User Logs In

   • User clicks login link (redirects to client login page from initiate_login_uri)
   • Client generates OAuth2 parameters (state, code_verifier for PKCE) client-side
   • User enters credentials and completes OAuth2 flow
   • If need_reset_password: true, user is forced to change password on first login

Important Create User Fields

Field	Required	Description	Example
userEntity.email	Yes*	User email address	[email protected]
userEntity.mobile_number	Yes*	User mobile number	+491234567890
userEntity.username	Yes*	Username	johndoe
userEntity.password	Conditional	User password (required unless generate_password: true)	SecurePass123!
userEntity.given_name	No	User's first name	John
userEntity.family_name	No	User's last name	Doe
userEntity.userStatus	No	User status (default: VERIFIED)	VERIFIED or PENDING
userEntity.email_verified	No	Email verification status	true
userEntity.groups	No	Groups and roles to assign	[{groupId: "CIDAAS_USERS", roles: ["USER"]}]
userEntity.need_reset_password	No	Force password change on first login	true
client_id	Required when notify_user=true	Unique app client ID. Mandatory for notification login link generation.	uuid-here
redirect_uri	Required when notify_user=true	App redirect URI used in the welcome notification login link; must match a redirect_uri on the app	https://yourapp.com/callback
response_type	Required when notify_user=true	OAuth2 response type for the generated login link; must be one of the app's configured response_types (defaults to code)	code
primaryType	No	Welcome notification channel: email, sms, or username (defaults to email when email is present)	email
notify_user	No	Send welcome email/SMS notification (default: true). When true, triggers login link generation and requires OAuth parameters.	true
generate_password	No	Auto-generate password	true
initiate_login_uri	Recommended	Client login page URL — see below	https://yourapp.com/login

Note: At least one identifier (email, mobile_number, or username) is required.

initiate_login_uri

Recommended when notify_user is true.

• Configure on the app in app settings. This ensures the client can generate OAuth2 parameters (state, code_verifier for PKCE) client-side for seamless login after user creation.
• Becomes {{login_link}} in USER_CREATED (verified email or SMS).
• If omitted, cidaas builds an authz URL from client_id, redirect_uri, and response_type.
• USER_CREATED_VERIFY (email_verified: false) uses {{verify_link}}.

Important Details

Required Permissions

• Scope: cidaas:users_write
• Roles: admin, secondary_admin, or user_create (in CIDAAS_ADMINS group)

Field Validations

• At least one identifier must be provided: email, mobile_number, or username
• Password must meet password policy requirements (unless generate_password: true)
• Email format must be valid (if provided)
• Mobile number format must be valid (if provided)
• Groups must exist and be allowed in app settings
• redirect_uri must match a URI configured on the app when used for login links in notifications
• Custom fields must be configured in Field Settings

User Status

• User account is created immediately with status VERIFIED (or as specified)
• User is immediately searchable in user search APIs
• User can login immediately with provided credentials

Create User Notification Templates

When notify_user is true, cidaas sends a USER_CREATED or USER_CREATED_VERIFY notification (email or SMS per primaryType).

Template Key: USER_CREATED

Used when:

• Email (primaryType: email) and email_verified is true
• SMS (primaryType: sms)

Template Variables:

• {{name}} - User's full name
• {{login_link}} - Login URL in the notification. Built from initiate_login_uri when provided in the request, or from client_id, redirect_uri, and response_type as a /authz-srv/authz URL.
• {{password}} - User's password
• {{account_name}} - Organization/tenant name
• {{user_name}} - Email or mobile number

Locale Support:

• Set via Accept-Language HTTP header (e.g., Accept-Language: de)
• Templates are localized based on user's locale

Template Key: USER_CREATED_VERIFY

Used when notify_user: true, email notification (primaryType: email), and email_verified is false.

Template Variables:

• {{name}} - User's full name
• {{verify_link}} - Account verification URL
• {{password}} - User's password
• {{account_name}} - Organization/tenant name

What the User Receives

• Personalized email/SMS with their name
• Clickable login link (or verification link if email not verified)
• Password (if not auto-generated, password is included)
• Account/organization name

Webhooks and Facts

When users are created, fact events (webhooks) are sent:

Event Types

• ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY: User created with self provider (email/password)
• ACCOUNT_CREATED_WITH_SOCIAL_IDENTITY: User created with social provider
• ACCOUNT_CIDAASIDENTITY_ADDED: Additional cidaas identity added (for subsequent identities)
• ACCOUNT_SOCIALIDENTITY_ADDED: Additional social identity added (for subsequent identities)

Fact Event Structure

• Object Type: users
• Object ID: The sub (unique user identifier)
• Webhook Attributes: ["provider", "requestId", "sub"]
• Use Case: Track user creation events, monitor onboarding, integrate with external systems

The sub allows you to:

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

Groups & Roles

Assigning Groups

• Assign Groups: Groups assigned during creation
• App Settings: Groups must be allowed in app settings (operations_allowed_groups)
• User Status: User account is immediately active and searchable

Required Roles

Operation	Required Roles
Create User	admin, secondary_admin, user_create

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: Create User

Required Roles: admin, secondary_admin or user_create

Create Admin User

1. Navigate to Users > Create User
2. Select Admin usertype
3. Enter identifiers (email, mobile, or username)
4. Set password (or generate automatically)
5. Configure groups and roles
6. Click Create User

Result: User receives email with login link and password.

Create Normal User

1. Navigate to Users > Create User
2. Select User usertype
3. Select client app (redirect URL auto-filled)
4. Enter identifiers
5. Configure user info and groups
6. Click Create User

Result: User receives email with login link and password.

Technical Integration

Endpoint	Method	Description	Link
Create User	POST	Create a new user with admin-set password	POST /users-srv/user/create/byadmin

Related Topics

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

info

Need Support?

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