Skip to main content

​
Users API

The users module allows you to interact with Wacht User records programmatically from your backend server. 
import { WachtClient } from "@wacht/backend";

const client = new WachtClient({ apiKey: process.env.WACHT_API_KEY });

​
Reading Users

​
listUsers()

Retrieves a paginated list of all users in your workspace. 
const response = await client.users.listUsers({ 
  limit: 10, 
  offset: 0 
});

console.log(`Found ${response.data.length} users.`);
​
options
ListUsersOptions

​
getUser(userId)

Retrieves a single user by their unique identifier. 
const user = await client.users.getUser("usr_abc123");
console.log(user.first_name);
​
userId
string
required
The unique ID of the user to fetch.

​
getUserByEmail(email)

Retrieves a single user based on an exact email address match. 
const user = await client.users.getUserByEmail("alice@example.com");
​
email
string
required
The exact email address of the user.

​
Mutating Users

​
createUser(request)

Provisions a new user into your workspace programmatically. This bypasses typical sign-up flows and automatically verifies specified identifiers if they are marked as such. 
const newUser = await client.users.createUser({
  first_name: "Alice",
  last_name: "Smith",
  email_address: "alice@example.com",
  password: "secure_placeholder",
  public_metadata: { role: "superuser" }
});
​
request
CreateUserRequest
required

​
updateUser(userId, request)

Update a user’s rudimentary properties or custom metadata. 
const updatedUser = await client.users.updateUser("usr_abc123", {
  first_name: "Alicia",
  private_metadata: { internal_crm_id: "crm_98765" }
});
​
userId
string
required
The unique ID of the user.
​
request
UpdateUserRequest
required

​
deleteUser(userId)

Permanently removes a user and cascades the deletion to their associated sessions, identities, and social connections. 
await client.users.deleteUser("usr_abc123");
​
userId
string
required
The unique ID of the user to permanently delete.

​
Managing Identifiers

Users in Wacht can have multiple email addresses and phone numbers. The users module exposes methods to manage these relational arrays.

​
Emails

  • client.users.listEmails(userId)
  • client.users.addEmail(userId, request)
  • client.users.updateEmail(userId, emailId, request)
  • client.users.deleteEmail(userId, emailId)

​
Phones

  • client.users.listPhones(userId)
  • client.users.addPhone(userId, request)
  • client.users.updatePhone(userId, phoneId, request)
  • client.users.deletePhone(userId, phoneId)

​
Authentication Management

​
updatePassword(userId, request)

Force an administrative reset of a user’s password. 
await client.users.updatePassword("usr_abc123", {
  new_password: "NewSecurePassword123!"
});
​
userId
string
required
The user ID.
​
request
UpdatePasswordRequest
required

​
deleteSocialConnection(userId, connectionId)

Unlinks a connected OAuth provider (like Google or GitHub) from the user’s profile. 
await client.users.deleteSocialConnection("usr_abc123", "conn_github_456");
​
userId
string
required
The user ID.
​
connectionId
string
required
The connection identifier to unlink.