SDKsTypeScript SDKAdmin API
User Management
Create, read, update, delete, and search users with the TypeScript SDK Admin API.
User Management
The Admin API provides full user lifecycle management. These methods require admin scope (users:read, users:write) or an API key with admin privileges.
listUsers()
List users with pagination, filtering, and sorting.
client.admin.listUsers(params?: ListUsersParams): Promise<UserList>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
pageSize | number | no | Users per page (default: 25, max: 250) |
pageToken | string | no | Pagination token from previous response |
filter | string | no | Filter expression (CEL syntax) |
orderBy | string | no | Sort field and direction (e.g., "created_at desc") |
organizationId | string | no | Filter by organization membership |
Returns
interface UserList {
users: User[];
nextPageToken: string | null;
totalSize: number;
}Basic usage
import { AvnologyId } from "@avnology/sdk-typescript";
const client = new AvnologyId({
baseUrl: "https://api.id.avnology.com",
apiKey: "ak_live_...",
});
const result = await client.admin.listUsers({ pageSize: 50 });
for (const user of result.users) {
console.log(user.id, user.email, user.status);
}
console.log("Total users:", result.totalSize);Pagination
let pageToken: string | null = null;
const allUsers: User[] = [];
do {
const result = await client.admin.listUsers({
pageSize: 100,
pageToken: pageToken ?? undefined,
});
allUsers.push(...result.users);
pageToken = result.nextPageToken;
} while (pageToken);
console.log(`Fetched ${allUsers.length} total users`);Filtering
Use CEL-style filter expressions to search users.
// Find users by email domain
const acmeUsers = await client.admin.listUsers({
filter: 'email.endsWith("@acme.com")',
});
// Find verified users created after a date
const recentVerified = await client.admin.listUsers({
filter: 'status == "active" && created_at > timestamp("2026-01-01T00:00:00Z")',
orderBy: "created_at desc",
});
// Find users in a specific organization
const orgUsers = await client.admin.listUsers({
organizationId: "org_abc123",
});getUser()
Retrieve a single user by ID.
client.admin.getUser(params: GetUserParams): Promise<User>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
userId | string | yes | User ID (e.g., "usr_abc123") |
Returns
Promise<User> -- The user object with full profile and metadata.
Basic usage
const user = await client.admin.getUser({ userId: "usr_abc123" });
console.log(user.id); // "usr_abc123"
console.log(user.email); // "[email protected]"
console.log(user.emailVerified); // true
console.log(user.phone); // "+15550100"
console.log(user.name); // { first: "Jane", last: "Doe" }
console.log(user.status); // "active"
console.log(user.createdAt); // "2026-01-15T10:30:00Z"
console.log(user.lastLoginAt); // "2026-04-08T09:00:00Z"
console.log(user.organizationId); // "org_abc123"
console.log(user.mfaEnabled); // true
console.log(user.mfaMethods); // ["totp", "webauthn"]
console.log(user.metadata.public); // { plan: "pro" }
console.log(user.metadata.admin); // { notes: "VIP customer" }createUser()
Create a new user account programmatically. The user will receive a verification email unless you explicitly set the email as verified.
client.admin.createUser(params: CreateUserParams): Promise<User>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | string | yes | Email address |
password | string | no | Password (if omitted, user must set via recovery) |
traits | UserTraits | no | Profile data (name, phone, locale, timezone) |
organizationId | string | no | Add to organization on creation |
verified | boolean | no | Skip email verification (default: false) |
metadata | UserMetadata | no | Custom metadata (public + admin) |
Basic usage
const user = await client.admin.createUser({
email: "[email protected]",
password: "TempPassword123!",
traits: {
name: { first: "New", last: "User" },
},
organizationId: "org_abc123",
verified: true, // Skip email verification
metadata: {
public: { plan: "starter" },
admin: { source: "bulk-import" },
},
});
console.log("Created user:", user.id);Create user without password (invite flow)
const user = await client.admin.createUser({
email: "[email protected]",
traits: { name: { first: "Invited", last: "User" } },
organizationId: "org_abc123",
});
// Send an invitation email (user sets their password via recovery)
await client.requestRecovery({ email: "[email protected]" });updateUser()
Update a user's profile, status, or metadata. Uses field mask semantics -- only specified fields are updated.
client.admin.updateUser(params: UpdateUserParams): Promise<User>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
userId | string | yes | User ID |
traits | Partial<UserTraits> | no | Fields to update |
status | "active" | "disabled" | no | Account status |
metadata | Partial<UserMetadata> | no | Custom metadata to merge |
Basic usage
const updated = await client.admin.updateUser({
userId: "usr_abc123",
traits: {
name: { first: "Jane", last: "Smith" }, // Changed last name
phone: "+15559999", // Updated phone
},
metadata: {
admin: { notes: "Updated by admin on 2026-04-08" },
},
});
// Disable a user
await client.admin.updateUser({
userId: "usr_abc123",
status: "disabled",
});deleteUser()
Permanently delete a user and all associated data (GDPR Art. 17).
client.admin.deleteUser(params: DeleteUserParams): Promise<void>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
userId | string | yes | User ID |
Basic usage
await client.admin.deleteUser({ userId: "usr_abc123" });
console.log("User permanently deleted.");searchUsers()
Full-text search across user email, name, and metadata.
client.admin.searchUsers(params: SearchUsersParams): Promise<UserList>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | yes | Search query |
pageSize | number | no | Results per page (default: 25) |
pageToken | string | no | Pagination token |
Basic usage
const results = await client.admin.searchUsers({
query: "jane",
pageSize: 10,
});
for (const user of results.users) {
console.log(user.email, user.name);
}bulkImportUsers()
Import multiple users at once. Supports partial failures -- successfully created users are returned alongside errors for failures.
client.admin.bulkImportUsers(params: BulkImportParams): Promise<BulkImportResult>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
users | CreateUserParams[] | yes | Array of users to create (max: 500) |
organizationId | string | no | Add all users to this organization |
Returns
interface BulkImportResult {
created: User[];
errors: { index: number; error: AvnologyIdError }[];
totalCreated: number;
totalFailed: number;
}Basic usage
const result = await client.admin.bulkImportUsers({
users: [
{ email: "[email protected]", traits: { name: { first: "Alice" } } },
{ email: "[email protected]", traits: { name: { first: "Bob" } } },
{ email: "[email protected]", traits: { name: { first: "Duplicate" } } }, // Will fail
],
organizationId: "org_abc123",
});
console.log(`Created: ${result.totalCreated}, Failed: ${result.totalFailed}`);
for (const err of result.errors) {
console.error(`User ${err.index} failed:`, err.error.message);
}Common errors
| Error class | HTTP status | When |
|---|---|---|
NotFoundError | 404 | User not found |
DuplicateAccountError | 409 | Email already exists |
ForbiddenError | 403 | Insufficient admin permissions |
ValidationError | 422 | Invalid field values |
RateLimitError | 429 | Too many requests |
See also
- Organizations -- Organization management
- Groups -- Group membership
- User type -- User type definition