User Status & Lifecycle

CORTEX implements a comprehensive user status system to control account access and lifecycle.

User Statuses

Status	Description	Can Login
ACTIVE	Normal, functioning account	Yes
SUSPENDED	Temporarily disabled	No
INACTIVE	Permanently disabled (soft-deleted)	No

Status Transitions

┌─────────────────────────────────────────────────────┐
│                                                     │
│  ┌──────────┐   suspend    ┌───────────┐           │
│  │  ACTIVE  │─────────────▶│ SUSPENDED │           │
│  │          │              │           │           │
│  │          │◀─────────────│           │           │
│  └──────────┘  reactivate  └───────────┘           │
│       │                          │                 │
│       │ delete                   │ delete          │
│       ▼                          ▼                 │
│  ┌───────────────────────────────────────┐        │
│  │              INACTIVE                  │        │
│  │     (cannot be reactivated)           │        │
│  └───────────────────────────────────────┘        │
│                                                     │
└─────────────────────────────────────────────────────┘

Suspend User

Temporarily disable a user account.

Endpoint

POST /users/:id/suspend

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "jane.smith@example.com",
  "status": "SUSPENDED",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

What Happens on Suspension

1. User status changes to SUSPENDED
2. All active sessions are terminated
3. Refresh tokens are invalidated
4. User cannot log in
5. API requests with existing access tokens continue until they expire

tip

Use suspension for temporary account lockouts, such as when investigating suspicious activity or during offboarding processes.

Reactivate User

Restore a suspended user's access.

Endpoint

POST /users/:id/reactivate

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "jane.smith@example.com",
  "status": "ACTIVE",
  "updatedAt": "2024-01-15T14:00:00.000Z"
}

What Happens on Reactivation

1. User status changes to ACTIVE
2. User can log in again
3. Role assignments remain intact

caution

You cannot reactivate a user with INACTIVE status. Inactive users must be re-created.

Delete User (Soft Delete)

Permanently disable a user account.

Endpoint

DELETE /users/:id

Response (204 No Content)

What Happens on Deletion

1. User status changes to INACTIVE
2. All sessions are terminated
3. All role assignments are revoked
4. Audit log records the deletion
5. User data is retained for audit purposes

Warning

Deletion is permanent in terms of account access. The user cannot be reactivated. However, their data is retained for compliance and audit purposes.

Status Change via PATCH

You can also change status directly:

Endpoint

PATCH /users/:id

Request

{
  "status": "SUSPENDED"
}

Automation: Auto-Suspension

Configure automatic suspension in tenant settings:

{
  "security": {
    "autoSuspendInactiveDays": 90
  }
}

Users inactive for 90 days will be automatically suspended.

Code Examples

TypeScript

class UserStatusManager {
  constructor(private accessToken: string) {}

  private async request(url: string, method: string) {
    const response = await fetch(url, {
      method,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
      },
    });
    return response.json();
  }

  async suspendUser(userId: string) {
    return this.request(
      `http://localhost:8091/users/${userId}/suspend`,
      'POST'
    );
  }

  async reactivateUser(userId: string) {
    return this.request(
      `http://localhost:8091/users/${userId}/reactivate`,
      'POST'
    );
  }

  async deleteUser(userId: string) {
    await fetch(`http://localhost:8091/users/${userId}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
      },
    });
  }
}

// Usage
const manager = new UserStatusManager(accessToken);

// Suspend user
await manager.suspendUser('user-id');

// Later, reactivate
await manager.reactivateUser('user-id');

cURL

# Suspend user
curl -X POST http://localhost:8091/users/550e8400-e29b-41d4-a716-446655440000/suspend \
  -H "Authorization: Bearer <access-token>"

# Reactivate user
curl -X POST http://localhost:8091/users/550e8400-e29b-41d4-a716-446655440000/reactivate \
  -H "Authorization: Bearer <access-token>"

# Delete user
curl -X DELETE http://localhost:8091/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <access-token>"

Audit Trail

All status changes are logged:

{
  "action": "USER_SUSPENDED",
  "resourceType": "USER",
  "resourceId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "admin-user-id",
  "metadata": {
    "previousStatus": "ACTIVE",
    "newStatus": "SUSPENDED",
    "reason": "Security review"
  }
}