4. User Account Suspension and Deletion

User Account Suspension and Deletion

This scenario demonstrates how administrators can suspend and delete user accounts within Circularo. These administrative actions are essential for managing user access, maintaining security, and handling employee departures or organizational changes.

Key features:

Suspend user accounts to temporarily disable access without losing user data
Permanently delete user accounts when they are no longer needed
Manage user lifecycle from creation through suspension to deletion
Implement proper offboarding processes in your organization

Prerequisites

Before suspending or deleting user accounts, you need:

A valid authentication token with administrative privileges
Knowledge of the user ID (typically email address) you want to suspend or delete
Understanding of the implications of suspension versus deletion

User account suspension and deletion require administrator privileges. Only organization administrators or global administrators can perform these operations.

Understanding Account States

Circularo supports different user account states that determine access and functionality:

Active: Normal account with full access based on assigned permissions
Suspended: Temporarily disabled account that preserves user data but prevents login
Deleted: Permanently removed account with no recovery option

Suspension is reversible and preserves all user data and associations, making it ideal for temporary deactivation. Deletion is permanent and removes user data from the system.

Step 1 - Suspend User Account

This endpoint demonstrates how to suspend a user account. Suspension is a reversible action that temporarily prevents the user from accessing the system while preserving all their data and associations.

Changes the user's status to "suspended" to prevent system access
Preserves all user data, group memberships, and document associations
Takes effect immediately
Can be reversed by changing the status back to "active"

Account suspension is ideal for temporary deactivation scenarios such as pending investigations or when an employee's status is uncertain.

Endpoint

CODE

PUT /users/:id

Request

JSON

PUT /users/derek.trotter@circularo.com?token=nsffiYK7lRfWYya3SRJW3qCdmhs1UelLfhwEh94S1TqqgEtavSLoDbMZdKiC0Xl5

Content-Type: application/json

{
  "status": "suspended"  //Change status to \"suspended\" to disable account access
}

Response

JSON

{
  "status": "SUCCESS"
}

The user account has been successfully suspended. The user will no longer be able to log in or access the system until the account is reactivated.

To reactivate a suspended account, simply update the user's status back to "active" using the same endpoint.

Step 2 - Delete User Account

This endpoint demonstrates how to permanently delete a user account. Deletion is an irreversible action that removes the user and their data from the system.

Permanently removes the user account from the system
Deletes user-specific data and personal information
Breaks associations with groups and organizations
Cannot be undone - deleted accounts cannot be recovered

Account deletion is permanent and cannot be reversed. Make sure to back up any important user data before proceeding with deletion.

Endpoint

CODE

DELETE /users/:id

Request

JSON

DELETE /users/derek.trotter@circularo.com?token=nsffiYK7lRfWYya3SRJW3qCdmhs1UelLfhwEh94S1TqqgEtavSLoDbMZdKiC0Xl5

Response

JSON

{
  "status": "SUCCESS"
}

The user account has been permanently deleted from the system. All user data and associations have been removed.

The user account has been completely removed from the system
Personal information associated with the user has been deleted
Document ownership and history records may be affected

For temporary deactivation with the option to restore access later, consider using account suspension instead of deletion.

User Account Suspension and Deletion Summary

You have successfully learned how to suspend and delete user accounts in the Circularo system.

Key Concepts

Account Suspension: Temporary deactivation that preserves user data
Account Deletion: Permanent removal of user accounts and data
User Lifecycle Management: Controlling the complete user journey from creation to deletion
Administrative Control: Centralized management of user access and status

Next Steps

With your understanding of user account suspension and deletion, you can now:

Implement proper offboarding workflows in your integration
Create automated processes for handling employee departures
Maintain appropriate security by promptly suspending or deleting accounts when needed
Develop policies for determining when to suspend versus delete accounts
Ensure compliance with data retention and privacy regulations

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT

// User account suspension and deletion example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_ADMIN_TOKEN"; // Must have administrative privileges
const USER_ID = "user@example.com"; // ID of the user to manage

try {
    // Step 1: Suspend user account
    const suspendResponse = await fetch(`${URL}${API_PATH}/users/${USER_ID}?token=${TOKEN}`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            status: "suspended"
        })
    });
    if (!suspendResponse.ok) {
        throw new Error(`Account suspension failed: ${suspendResponse.status} ${suspendResponse.statusText}`);
    }

    const suspendResult = await suspendResponse.json();
    console.log("User account suspended successfully:", suspendResult);

    // Step 2: Delete user account
    const deleteResponse = await fetch(`${URL}${API_PATH}/users/${USER_ID}?token=${TOKEN}`, {
        method: 'DELETE'
    });
    if (!deleteResponse.ok) {
        throw new Error(`Account deletion failed: ${deleteResponse.status} ${deleteResponse.statusText}`);
    }

    const deleteResult = await deleteResponse.json();
    console.log("User account deleted permanently:", deleteResult);

} catch (error) {
    console.error('Error managing user account:', error.message);
}