Skip to main content
POST
https://asteragents.com/api
/
admin
/
bulkRemove
Bulk User Removal
curl --request POST \
  --url https://asteragents.com/api/admin/bulkRemove \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userIds": [
    {}
  ]
}
'
{
  "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
​
errors
array
Array of failed removals (only present if there were failures)

​
Examples

curl -X POST https://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.