Get Organization Users

Retrieve all users in your organization with their details, roles, activity status, and metadata

DEPRECATED: This endpoint has been replaced by the new RESTful API structure.

Please migrate to:

• GET /admin/users - For active users
• GET /admin/invitations - For pending invitations

This endpoint will be removed in a future version.

This endpoint requires organization admin privileges. Only users with the org:admin role can access organization user data.

Returns a list of all users and pending invitations for the organization, including their profile information, roles, activity status, and custom metadata. Perfect for user management automation and bulk operations.

Authentication

Authorization · string · required

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

Query Parameters

activityStatus · string

Filter users by activity status. Options: active, pending, inactive

role · string

Filter users by organization role. Options: org:admin, org:member

Response

Returns an array of user objects with comprehensive details:

id · string

Unique Clerk user identifier. null for pending invitations that haven’t been accepted.

email · string

User’s email address

firstName · string

User’s first name

lastName · string

User’s last name

username · string

User’s username (if set)

profileImageUrl · string

URL to user’s profile image/avatar

lastSignInAt · string

ISO 8601 timestamp of user’s last sign-in

publicMetadata · object

Organization-scoped user metadata (department, role, vnum, etc.). Each organization maintains separate metadata for shared users.

createdAt · string

ISO 8601 timestamp when user account was created

role · string

User’s role in the organization (e.g., “org:admin”, “org:member”)

activityStatus · string

User’s activity status: active (current member), pending (invitation sent but not accepted), inactive (invitation revoked)

invitationStatus · string

Clerk invitation status if applicable: pending, accepted, revoked, or null for users without invitation history

invitationCreatedAt · string

ISO 8601 timestamp when invitation was created, or null for users without invitation history

Examples

curl -X GET "https://asteragents.com/api/admin/getUsersInOrg?activityStatus=active&role=org:admin" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Codes

400 · object

Bad Request - User is not part of any organization

401 · object

Unauthorized - Invalid or missing authentication

403 · object

Forbidden - User is not an admin in the organization

405 · object

Method Not Allowed - Only GET requests are accepted

500 · object

Internal Server Error - Unexpected error occurred

Use Cases

Bulk User Operations

Filter and process users based on metadata:

// Find all users in engineering department
const engineeringUsers = users.filter(user => 
  user.publicMetadata?.department === 'engineering'
);

// Find users by vnum
const specificUsers = users.filter(user => 
  user.publicMetadata?.vnum === '123'
);

User Management Dashboard

Build custom admin interfaces with complete user data:

# Create user summary report
for user in users:
    print(f"{user['email']} - {user['role']} - Last active: {user['lastSignInAt']}")

Invitation Status Check

Use this endpoint to verify which users have accepted invitations:

// Users with recent sign-ins have likely accepted invitations
const activeUsers = users.filter(user => user.lastSignInAt);
const pendingUsers = users.filter(user => !user.lastSignInAt);

Features

Complete User Data: Access all user profile information, roles, and custom metadata in a single request.

• Organization-Scoped Metadata: Each organization maintains separate metadata for users - perfect for multi-org scenarios
• Metadata Filtering: Use publicMetadata to filter users by department, role, vnum, or any custom fields within your organization
• Role Management: See each user’s organization role (admin vs member)
• Activity Tracking: Check last sign-in times to identify active vs inactive users
• Bulk Operations: Process multiple users programmatically for invitations, role changes, etc.

Notes

• Results are ordered by email address alphabetically
• Only returns users who are active members of the organization
• Metadata is organization-scoped: Users in multiple organizations have separate metadata per org
• Metadata structure depends on what was set during user invitation or updates via Update User Metadata
• lastSignInAt will be null for users who haven’t signed in yet (pending invitations)
• Use this data to identify users for bulk operations like role updates or removal