Transactional

Users

Manage end-user accounts, profiles, and authentication.

Overview

End users are the people who authenticate with your application. Transactional Auth manages user accounts, profiles, credentials, and identity linking.

User Lifecycle

Created→Pending Verification→Active→Blocked

Users can be unblocked and returned to Active status

User Status

StatusDescription
ACTIVEUser can log in and access the application
PENDING_VERIFICATIONAwaiting email or phone verification
BLOCKEDUser is blocked from logging in
DEACTIVATEDUser account is deactivated

Creating Users

Via API

TypeScript:

const user = await client.auth.users.create({
  email: 'user@example.com',
  password: 'SecurePassword123!',
  emailVerified: false,
  profile: {
    firstName: 'John',
    lastName: 'Doe',
    picture: 'https://example.com/avatar.jpg',
  },
  metadata: {
    plan: 'pro',
    source: 'signup',
  },
});
 
console.log('User ID:', user.id);
console.log('External ID:', user.externalId);

Python:

user = client.auth.users.create(
    email="user@example.com",
    password="SecurePassword123!",
    email_verified=False,
    profile={
        "firstName": "John",
        "lastName": "Doe",
    },
    metadata={
        "plan": "pro",
        "source": "signup",
    },
)
 
print(f"User ID: {user.id}")

Self-Registration

Users can register through your login flow:

// User submits registration form
const result = await client.auth.users.register({
  email: 'user@example.com',
  password: 'SecurePassword123!',
  profile: {
    firstName: 'John',
    lastName: 'Doe',
  },
});
 
// Send verification email
if (!result.emailVerified) {
  await client.auth.users.sendVerificationEmail(result.id);
}

Retrieving Users

Get by ID

const user = await client.auth.users.get('user_xxx');

Get by Email

const user = await client.auth.users.getByEmail('user@example.com');

Get by External ID

const user = await client.auth.users.getByExternalId('your-system-id-123');

List Users

const users = await client.auth.users.list({
  count: 50,
  offset: 0,
  status: 'ACTIVE',
  search: 'john',
});
 
for (const user of users.data) {
  console.log(`${user.email}: ${user.status}`);
}

Updating Users

await client.auth.users.update('user_xxx', {
  profile: {
    firstName: 'Jonathan',
    lastName: 'Doe',
  },
  metadata: {
    plan: 'enterprise',
  },
});

User Profile

The profile contains user information:

FieldDescription
firstNameUser's first name
lastNameUser's last name
displayNameDisplay name
pictureProfile picture URL
localePreferred locale
timezonePreferred timezone
await client.auth.users.update('user_xxx', {
  profile: {
    firstName: 'John',
    lastName: 'Doe',
    displayName: 'John D.',
    picture: 'https://example.com/avatar.jpg',
    locale: 'en-US',
    timezone: 'America/New_York',
  },
});

User Metadata

Store custom data with users:

User Metadata (Editable by User)

// Data the user can modify
await client.auth.users.update('user_xxx', {
  metadata: {
    theme: 'dark',
    notifications: 'enabled',
  },
});

App Metadata (Admin Only)

// Data only your application can modify
await client.auth.users.update('user_xxx', {
  appMetadata: {
    plan: 'enterprise',
    stripeCustomerId: 'cus_xxx',
    permissions: ['read', 'write', 'admin'],
  },
});

Email Verification

Send Verification Email

await client.auth.users.sendVerificationEmail('user_xxx');

Verify Email

await client.auth.users.verifyEmail('user_xxx', {
  code: '123456',
});

Check Verification Status

const user = await client.auth.users.get('user_xxx');
if (user.emailVerified) {
  console.log('Email is verified');
}

Password Management

Change Password

// User changes their own password
await client.auth.users.changePassword('user_xxx', {
  currentPassword: 'OldPassword123!',
  newPassword: 'NewPassword456!',
});

Reset Password (Admin)

// Admin resets password
await client.auth.users.resetPassword('user_xxx', {
  password: 'TemporaryPassword123!',
  requireChange: true, // Force change on next login
});

Send Password Reset Email

await client.auth.users.sendPasswordResetEmail('user@example.com');

Blocking Users

Block a User

await client.auth.users.block('user_xxx');

Blocked users:

  • Cannot log in
  • Existing sessions are invalidated
  • API calls with their tokens fail

Unblock a User

await client.auth.users.unblock('user_xxx');

Deleting Users

await client.auth.users.delete('user_xxx');

Warning: This permanently deletes the user and all associated data.

User Identities

Users can have linked identities from social/SSO providers:

List Identities

const identities = await client.auth.users.listIdentities('user_xxx');
for (const identity of identities) {
  console.log(`${identity.provider}: ${identity.providerId}`);
}

Link Identity

// After social login, link to existing user
await client.auth.users.linkIdentity('user_xxx', {
  provider: 'google',
  providerId: 'google-user-id',
  accessToken: 'google-access-token',
});

Unlink Identity

await client.auth.users.unlinkIdentity('user_xxx', {
  provider: 'google',
  providerId: 'google-user-id',
});

Login History

Track user login activity:

const user = await client.auth.users.get('user_xxx');
 
console.log('Login count:', user.loginCount);
console.log('Last login:', user.lastLoginAt);
console.log('Last IP:', user.lastLoginIp);

Bulk Operations

Import Users

const results = await client.auth.users.import([
  {
    email: 'user1@example.com',
    password: 'hashed:$2b$...',
    emailVerified: true,
  },
  {
    email: 'user2@example.com',
    password: 'hashed:$2b$...',
    emailVerified: true,
  },
]);
 
console.log(`Imported: ${results.success}, Failed: ${results.failed}`);

Export Users

const users = await client.auth.users.export({
  format: 'csv',
  fields: ['id', 'email', 'profile', 'createdAt'],
});

External IDs

Map users to your own system:

// Create user with external ID
const user = await client.auth.users.create({
  email: 'user@example.com',
  externalId: 'your-system-user-id',
});
 
// Look up by external ID
const user = await client.auth.users.getByExternalId('your-system-user-id');

Next Steps