Bulk User Removal

Remove multiple users from your organization at once

POST /admin/bulkRemove

Bulk User Removal

cURL

curl --request POST \
  --url https://www.asteragents.com/api/admin/bulkRemove \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userIds": [
    {}
  ]
}
'

200

{
  "207": {},
  "400": {},
  "401": {},
  "403": {},
  "405": {},
  "success": true,
  "total": 123,
  "successful": 123,
  "failed": 123,
  "results": [
    {
      "userId": "<string>",
      "success": true
    }
  ],
  "errors": [
    {
      "userId": "<string>",
      "success": true,
      "error": "<string>"
    }
  ]
}

DEPRECATED: This endpoint has been replaced by DELETE /admin/users.

The new endpoint provides:

• Cleaner RESTful structure
• Better separation between users and invitations
• Consistent response format

This endpoint will be removed in a future version.

This endpoint requires organization admin privileges. Only users with the org:admin role can bulk remove users from their organization.

Users cannot remove themselves from the organization using this endpoint. This prevents accidental lockouts.

Authentication

Authorization · string · required

Bearer token for authentication. Must be from a user with org:admin role.

Body

userIds · array · required

Array of Clerk user IDs to remove from the organization (1-50 users per request)

Response

success · boolean

Whether all users were successfully removed

total · number

Total number of users requested to be removed

successful · number

Number of users successfully removed

failed · number

Number of users that failed to be removed

results · array

Array of successful removal results

Show Result Object

userId · string

Clerk user ID that was successfully removed

success · boolean

Whether this specific removal was successful (always true in results array)

errors · array

Array of failed removals (only present if there were failures)

Show Error Object

userId · string

Clerk user ID that failed to be removed

success · boolean

Always false for error objects

error · string

Description of what went wrong

Examples

Basic Removal

curl -X POST https://www.asteragents.com/api/admin/bulkRemove \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": [
      "user_2ABC123DEF",
      "user_2XYZ789GHI"
    ]
  }'

Error Codes

400 · object

Bad Request - Invalid request data, validation errors, or attempting to remove yourself

401 · object

Unauthorized - Invalid or missing authentication

403 · object

Forbidden - User is not an admin in the organization

405 · object

Method Not Allowed - Only POST requests are accepted

207 · object

Multi-Status - Some removals succeeded, others failed (partial success)

Workflow

Step 1: Get User IDs

First, use the Get Organization Users endpoint to retrieve user IDs:

// Get all users in organization
const usersResponse = await fetch('/api/admin/getUsersInOrg', {
  headers: { 'Authorization': 'Bearer ' + token }
});
const users = await usersResponse.json();

// Filter users you want to remove (e.g., by department)
// Note: publicMetadata is organization-scoped
const usersToRemove = users
  .filter(user => user.publicMetadata?.department === 'marketing')
  .map(user => user.id);

Step 2: Bulk Remove Users

Then use those IDs to remove users from the organization:

const removeResponse = await fetch('/api/admin/bulkRemove', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userIds: usersToRemove
  })
});

Use Cases

Department Restructuring

Remove all users from a specific department:

# Get all users
users = requests.get('/api/admin/getUsersInOrg', headers=headers).json()

# Filter by department
marketing_users = [
    user['id'] for user in users 
    if user.get('publicMetadata', {}).get('department') == 'marketing'
]

# Remove them
response = requests.post('/api/admin/bulkRemove', 
    headers=headers, json={'userIds': marketing_users})

Inactive User Cleanup

Remove users who haven’t signed in recently:

const cutoffDate = new Date('2023-01-01');
const inactiveUsers = users
  .filter(user => {
    const lastSignIn = user.lastSignInAt ? new Date(user.lastSignInAt) : null;
    return !lastSignIn || lastSignIn < cutoffDate;
  })
  .map(user => user.id);

// Remove inactive users
await fetch('/api/admin/bulkRemove', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({ userIds: inactiveUsers })
});

Role-Based Removal

Remove users with specific roles or metadata:

# Remove all temporary contractors
temp_contractors = [
    user['id'] for user in users 
    if user.get('publicMetadata', {}).get('role') == 'temp_contractor'
]

Features

Safe Operations: Built-in protection against self-removal and comprehensive error handling.

• Self-Protection: Admins cannot accidentally remove themselves
• Batch Processing: Handle up to 50 users per request efficiently
• Detailed Results: Know exactly which users were removed and which failed
• Partial Success: Continue processing even if some removals fail

Security Notes

• Only organization admins can remove users
• Removed users lose access to the organization immediately
• Organization-scoped metadata is deleted when a user is removed from the organization
• Users can be re-invited after removal (with fresh metadata)
• Action is logged in Clerk audit logs
• Webhooks will fire for organizationMembership.deleted events

Limits

• Batch Size: 1-50 user IDs per request
• User ID Validation: All user IDs must be valid Clerk user identifiers
• Rate Limiting: Subject to Clerk’s API rate limits
• Self-Removal: Cannot remove your own user ID (will fail with error)

Use this endpoint in combination with Get Organization Users to build powerful user management workflows.