User entity reference

Understand how user entities work in SecureAuth and what each attribute controls for authentication and access management.

💡 Why this matters
User entities determine how authentication works, what data gets stored, and how you can manage users across your applications.

What is a user entity

A user entity contains all the information SecureAuth stores about an individual user. This includes operational attributes that control authentication flows and optional custom attributes for your business needs.

Two types of attributes:

• Operational attributes - Required by SecureAuth for authentication and user management
• Custom attributes - Optional fields you define for business requirements

Operational attributes

These attributes control how SecureAuth handles authentication and user management.

Status

Controls what actions a user can perform in your system.

Status	What it allows	When to use
new	Account activation only	New user registrations
active	Full authentication	Normal operational users
inactive	No authentication	Suspended or temporary users
deleted	No actions	Archived users

Status flow rules:

• Only new users can complete account activation
• Only active users can authenticate
• Administrators can change any user to inactive or new

Identifiers

Unique keys that identify users during authentication and API calls.

Identifier Type	Format	Example	Use Case
email	Valid email format	user@company.com	Email-based login
mobile	E164 format	+12345678901	SMS authentication
uid	ASCII characters	user123	Custom username
external	ASCII characters	emp_987654	Integration with HR systems

Key rules:

• Each identifier must be unique within a user population
• Users can have multiple identifiers of different types
• Identifiers serve as authentication usernames

Addresses

Contact information for verification codes and account recovery.

Address Type	Format	Verification Required	Purpose
email	Valid email	Optional	Password reset, notifications
mobile	E164 format	Optional	SMS codes, alerts

Verification states:

• Verified addresses - Unique per population, used for account recovery
• Unverified addresses - Can be shared between users, limited functionality

Address rules:

• Verified addresses can only belong to one user per population
• Unverified addresses can be shared between users
• Address verification prevents account takeover

Credentials

Authentication methods stored for each user.

Credential Type	Description	User Limit
password	Encrypted password hash	One per user
webauthn	FIDO2/WebAuthn keys	One per user

Security notes:

• Users can have multiple credential types simultaneously
• Only one password and one WebAuthn credential per user
• Credentials are encrypted and cannot be retrieved in plain text

Timestamps

Track user account activity and changes.

Timestamp	Tracks	Administrative Use
created_at	Account creation	Audit trails, compliance
updated_at	Last profile change	Monitoring user activity
status_updated_at	Status changes	Security investigations

Custom attributes

Add business-specific data fields to user entities for your organization's needs.

Common examples:

• Employee ID
• Department
• Role or permissions
• Account numbers
• Risk scores

⚠️ Security note: Avoid storing sensitive data like SSNs or payment information in custom attributes

Next step: Define custom user attributes →