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

50: ## Prerequisites 51: 52: Before creating users: 53: 54: - Field Settings configured 55: - User Groups created (if needed) 56: - User Roles defined (if needed) 57: - App Settings configured 58: - initiate_login_uri configured in app settings (recommended for OAuth2 compliance) 59: 60: ## Conditional Required Fields 61: 62: 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. 63: 64: ### Parameter Validation Matrix 65: 66: | Parameter | Status when notify_user=true | Status when notify_user=false | Description & Validation Rules | 67: |-----------|-------------------------------|--------------------------------|--------------------------------| 68: | 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). | 69: | 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). | 70: | redirect_uri | Required | Optional | Target redirect URL for authentication redirect. Must strictly match one of the registered redirect_uris in the application configuration. | 71: | 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. | 72: 73: > 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). 74: 75: ## User Creation Flow 76: 77: The following sequence diagram illustrates the complete user creation process from creation to user login: 78: 79: mermaid 80: sequenceDiagram 81: participant Admin 82: participant API as POST /users-srv/user/create/byadmin 83: participant System as cidaas System 84: participant Email as Email/SMS Service 85: participant User 86: participant Client as Client Login Page 87: participant Authz as /authz-srv/authz 88: 89: Admin->>API: Create user<br/>(with password) 90: Note over API: User account created<br/>immediately 91: API->>System: Store user account<br/>(sub, email, groups, etc.) 92: API->>System: Generate login link<br/>(using initiate_login_uri from app<br/>or generated authz URL) 93: API->>Email: Send welcome email/SMS<br/>(with login link and password) 94: API-->>Admin: Return sub (user ID) 95: Note over System: Fact event (webhook) sent<br/>automatically to external systems 96: 97: Email->>User: Email with login link<br/>(and password) 98: 99: User->>System: Clicks login link 100: System->>Client: Redirect to client login page<br/>(from initiate_login_uri) 101: Note over Client: Client creates OAuth2 params<br/>(state, code_verifier, etc.) 102: Client->>Authz: Redirect to authz<br/>(with OAuth2 params) 103: Authz->>User: Prompt for login 104: User->>Authz: Enter credentials<br/>(email + password) 105: Authz->>Client: Redirect with token/code 106: Note over Client,Authz: OAuth2 params (state, code_verifier)<br/>allow user to complete login flow 107: 108: 109: ### Flow Steps Explained 110: 111: 1. Admin Creates User 112: - Admin calls POST /users-srv/user/create/byadmin with user data and password 113: - API Reference: See Create User API for request examples 114: 115: 2. User Account Created 116: - User account is created immediately with sub (unique identifier) 117: - User is immediately searchable in user search APIs 118: - Groups and roles are assigned during creation 119: - If need_reset_password: true, password reset is configured for first login 120: 121: 3. Login Link Generation & Dependency Chain (when notify_user is true) 122: - 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. 123: - Link Resolution Priority: 124: 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. 125: 2. Fallback Authorization URL: If initiate_login_uri is not configured, cidaas dynamically constructs a authorization URL formatted as: 126: https://{tenant}/authz-srv/authz?client_id={client_id}&redirect_uri={redirect_uri}&response_type={response_type} 127: - Admin Special Handling: Users assigned to CIDAAS_ADMINS group receive {tenant}/admin-ui as the login link in email. 128: - 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}}. 129: 130: 4. Notification Sent 131: - Channel is determined by primaryType (email, sms, or username; defaults to email when the user has an email address) 132: - USER_CREATED (email with email_verified: true, or SMS): {{login_link}} targets initiate_login_uri or a built authz URL; includes password 133: - USER_CREATED_VERIFY (email with email_verified: false): includes {{verify_link}} for account verification 134: - Template variables: {{name}}, {{login_link}} or {{verify_link}}, {{password}}, {{account_name}} 135: 136: 5. User Logs In 137: - User clicks login link (redirects to client login page from initiate_login_uri) 138: - Client generates OAuth2 parameters (state, code_verifier for PKCE) client-side 139: - User enters credentials and completes OAuth2 flow 140: - If need_reset_password: true, user is forced to change password on first login 141: 142: ## Important Create User Fields 143: 144: | Field | Required | Description | Example | 145: |-------|----------|-------------|---------| 146: | userEntity.email | Yes* | User email address | [email protected] | 147: | userEntity.mobile_number | Yes* | User mobile number | +491234567890 | 148: | userEntity.username | Yes* | Username | johndoe | 149: | userEntity.password | Conditional | User password (required unless generate_password: true) | SecurePass123! | 150: | userEntity.given_name | No | User's first name | John | 151: | userEntity.family_name | No | User's last name | Doe | 152: | userEntity.userStatus | No | User status (default: VERIFIED) | VERIFIED or PENDING | 153: | userEntity.email_verified | No | Email verification status | true | 154: | userEntity.groups | No | Groups and roles to assign | [{groupId: "CIDAAS_USERS", roles: ["USER"]}] | 155: | userEntity.need_reset_password | No | Force password change on first login | true | 156: | client_id | Required when notify_user=true | Unique app client ID. Mandatory for notification login link generation. | uuid-here | 157: | 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 | 158: | 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 | 159: | primaryType | No | Welcome notification channel: email, sms, or username (defaults to email when email is present) | email | 160: | notify_user | No | Send welcome email/SMS notification (default: true). When true, triggers login link generation and requires OAuth parameters. | true | 161: | generate_password | No | Auto-generate password | true | 162: | 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].