User Status Management

User status management allows administrators to control user account states, enabling or disabling access to your application. This guide covers user status values, how status changes work, the API for changing status, email templates, and webhooks.

Purpose and Benefits

What is User Status?

User status represents the current state of a user account in cidaas. It determines whether a user can access your application and what actions they can perform.

Key Benefits

Benefit	Description
Access Control	Enable or disable user access to your application
Security Management	Quickly deactivate compromised or suspicious accounts
Account Lifecycle	Manage user accounts through their lifecycle (active, inactive, deleted)
Automated Token Revocation	Automatically revoke access tokens when status changes to declined
Audit Trail	Track status changes through webhooks and facts

User Status Values

cidaas supports the following user status values:

Status	Description	Use Case
VERIFIED	Active user account	User can log in and access the application
DECLINED	Inactive user account	User cannot log in; access is blocked
DELETED	Deleted user account	User account is marked for deletion (scheduled deletion)
PENDING	Pending verification	User account created but not yet verified (auto-activation disabled)

Status Transitions

The following table shows allowed status transitions:

Current Status	Allowed Transitions	Notes
VERIFIED	→ DECLINED, DELETED	Can deactivate or delete active users
DECLINED	→ VERIFIED, DELETED	Can reactivate or delete inactive users
DELETED	→ VERIFIED	Can restore deleted users (cancels scheduled deletion)
PENDING	→ VERIFIED	Can activate pending users

Important Notes:

• Status transitions are validated using IsFollowUpStatus function
• Invalid transitions will return a 400 Bad Request error
• Changing status from DELETED to VERIFIED automatically cancels any scheduled deletion requests

User Status Change Flow

The following sequence diagram illustrates the user status change process:

Flow Steps Explained

1. Admin Initiates Status Change

   • Admin calls PATCH /user-srv/users/{sub}/status with:
     • sub: User's subject identifier (path parameter)
     • userStatus: New status (VERIFIED or DECLINED)
     • user_status_reason (optional): Reason for status change
   • API Reference: See Change User Status API for request examples

2. System Validates Transition

   • System checks if the status transition is allowed using IsFollowUpStatus
   • If invalid, returns 400 Bad Request error

3. Status Update

   • User account status is updated in the database
   • user_status_reason is stored if provided

4. Token Revocation (if status = DECLINED)

   • All active access tokens for the user are automatically revoked
   • User cannot use existing tokens to access the application

5. Email Notification

   • Email is sent to the user's registered email address
   • Template: AFTER_ACTIVATE_USER (for VERIFIED) or AFTER_DE_ACTIVATE_USER (for DECLINED)

6. Webhook/Fact Event

   • Fact event is created and sent as webhook
   • Event type: ACCOUNT_ACTIVATED (for VERIFIED) or ACCOUNT_DEACTIVATED (for DECLINED)

Important Details

Required Permissions

• Scope: cidaas:users_write
• Roles: ADMIN, SECONDARY_ADMIN, or USER_CREATE
• Groups: User must be member of CIDAAS_ADMINS group

API Endpoint

Endpoint: PATCH /user-srv/users/{sub}/status

Path Parameters:

• sub (required): User's subject identifier (in URL path)

Request Body:

• sub (optional): User's subject identifier (can be omitted if provided in path)
• userStatus (required): New status (VERIFIED or DECLINED)
• user_status_reason (optional): Reason for status change

Note: The sub in the request body must match the sub in the path parameter if both are provided.

Response:

• 200 OK: Status updated successfully
• 400 Bad Request: Invalid status transition or missing required fields
• 401 Unauthorized: Missing or invalid authentication
• 404 Not Found: User not found

Email Templates

When user status is changed, an email notification is automatically sent to the user:

Template Key	Description	When Sent	Variables
AFTER_ACTIVATE_USER	Notification that account has been activated	When status changes to VERIFIED	{{name}}, {{account_name}}, {{reason}} (if provided)
AFTER_DE_ACTIVATE_USER	Notification that account has been deactivated	When status changes to DECLINED	{{name}}, {{account_name}}, {{reason}} (if provided)

Template Details:

• Locale: Based on Accept-Language header or tenant default
• Recipient: User's registered email address
• Processing Type: EMAIL
• Reason Field: If user_status_reason is provided, it's included in the email template variables

Webhooks and Facts

When user status is successfully changed, a fact event is automatically created and sent as a webhook:

Event Type	Object Type	Object ID	Description	When Triggered	Webhook Attributes
ACCOUNT_ACTIVATED	users	sub (user ID)	User account activated	Status changed to VERIFIED	["userStatus"]
ACCOUNT_DEACTIVATED	users	sub (user ID)	User account deactivated	Status changed to DECLINED	["userStatus"]

Webhook Payload Structure

New Value (UserStatusFact):

{
  "actor": "admin-sub",
  "sub": "user-sub",
  "userStatus": "VERIFIED",
  "clientID": "client-id"
}

Old Value (UserStatusFact):

{
  "actor": "admin-sub",
  "sub": "user-sub",
  "userStatus": "DECLINED",
  "clientID": "client-id"
}

Webhook URL: {public_url}/users-webapp/{objectType}/{objectId}

Token Revocation

When user status is changed to DECLINED:

• All active access tokens for the user are automatically revoked
• User cannot use existing tokens to access the application
• User must be reactivated (status changed to VERIFIED) to regain access

Note: Token revocation requires the cidaas:token_delete or cidaas:session_delete scope on the internal service token.

Special Cases

Restoring Deleted Users

If user status is changed from DELETED to VERIFIED:

• Any scheduled deletion requests are automatically cancelled
• User account is restored and can access the application again

Status Change Validation

• Status transitions are validated using IsFollowUpStatus function
• Only allowed transitions are permitted
• Attempting an invalid transition returns 400 Bad Request with error message

Technical Integration

Endpoint	Method	Description	Link
Change User Status	PUT	Update user status to VERIFIED or DECLINED	PUT /users-srv/user/changestatus

Related Topics

Topic	Description	Link
Account Structure	Overview of user account structure and components	Account Structure
User Deletion	Delete user accounts (scheduled or immediate)	User Deletion
Create User	Create new user accounts	Create User
Update User	Update user profile information	Update Account
Webhooks	Configure and manage webhooks	Webhook Management

Need Support?

Please contact us directly on our support page.