Account Structure

Understand how user accounts are organized in cidaas.

Quick Overview

• Unique ID: sub (subject) - technical identifier
• Multiple Identities: One account, multiple login methods
• Status: VERIFIED, PENDING, DECLINED, COMBINED, DELETED
• Groups & Roles: Access control and permissions

Account Structure

User Identifiers

Users can be identified by multiple methods:

Identifier	Example	Use Case
sub	753487e7-10bc-4e69-b3b2-4da33721ea3e	Technical ID (always unique)
email	[email protected]	Login & communication
mobile_number	+49123456789	Login & SMS verification
username	johndoe	Custom login identifier
Custom USERNAME fields	employee_id: 12345	Business-specific identifiers

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

Account Components

1. UserAccount (Top Level)

• sub: Unique user identifier
• userStatus: Account status (VERIFIED, PENDING, etc.)
• customFields: Business-specific data
• groups: User group memberships
• identities: Multiple login methods
• schedules: Planned or executed scheduled tasks (verification reminders, status changes, deletions)

2. Identity (Login Methods)

Each identity represents a login method:

Provider	Description	Example
self	Email/password login	provider: "self"
facebook	Facebook social login	provider: "facebook"
google	Google social login	provider: "google"
saml	SAML SSO	provider: "saml"

System Fields (per identity):

• given_name, family_name
• email, email_verified
• mobile_number, mobile_number_verified
• username
• address

3. Custom Fields

Business-specific attributes stored at account level:

Use Case	Example
Addresses	Postal address, billing address
References	Customer number, employee ID
Identifiers	Additional username fields

Setup: Field Settings

4. Groups & Roles

• Groups: Organize users (CIDAAS_USERS, CIDAAS_ADMINS, custom groups)
• Roles: Define permissions (ADMIN, USER, CUSTOMER)
• Learn more: User Groups

5. Schedules

• Schedules: Planned or executed scheduled tasks for the user
• Includes verification reminders, status changes, and deletion schedules
• Can be auto-created during registration or manually created via API
• Learn more: User Lifecycle Scheduling

6. User Account Status

Status	Description	User Can Login?	Notes
VERIFIED	Active user	✅ Yes	Can be changed via API
PENDING	Awaiting approval	❌ No	Can be changed via API
DECLINED	Inactive/suspended	❌ No	Can be changed via API
COMBINED	Merged with another account	❌ No	System-managed (not changeable via API)
DELETED	Deletion scheduled	❌ No	Managed via deletion APIs

Status Management: User Status Management - Detailed guide on status transitions, API usage, and workflows

Use Cases

Use Case 1: Multiple Login Methods

Scenario: User wants to login with email OR Google

1. User registers with email → Creates self identity
2. User links Google account → Creates google identity
3. Both identities linked to same sub
4. User can login with either method

Related: Account Linking

Use Case 2: Business Identifiers

Scenario: Track employee IDs alongside email

1. Configure custom field employee_id with type USERNAME
2. User can login with email OR employee ID
3. Both identifiers stored in userIds array

Related: Field Settings

Use Case 3: Account Status Management

Scenario: Admin needs to suspend a user

1. Change status: VERIFIED → DECLINED
2. User cannot login
3. Change back: DECLINED → VERIFIED
4. User can login again

Related: User Status Management

Related Topics

Topic	Description	Link
User Status Management	Manage account lifecycle and status changes	User Status Management
Field Setup	Configure custom fields	Field Settings
Groups & Roles	Access control	User Groups
Account Linking	Merge identities	Account Linking
Update Account	Modify user data	Update Account
User Deletion	Delete user accounts	User Deletion

warning

Need Support?

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