Users

Back-office user administration with client.users (plus the user↔app grant methods on client.apps). Routes are admin-gated server-side — most need system_admin or super_admin.

Reference: UsersModule · AppsModule · PoolsModule

import { createAuthClient } from '@rw3iss/auth-client';

const client = createAuthClient({
    apiBaseUrl: 'https://auth.ryanweiss.net/api/v1',
    appCode: 'auth-client-demo',
});
await client.ready();
await client.auth.login({ email: 'admin@ryanweiss.net', password: '…' });

Get all users for an application

client.users.list() is paginated and filterable by app and org membership:

const page1 = await client.users.list({ appId, page: 1, pageSize: 50 });
console.log(page1.total, page1.users.map((u) => u.email));

// other filters
await client.users.list({ search: 'ryan@' });
await client.users.list({ organizationId: orgId });

Bulk-resolve known identifiers in one round-trip instead of N queries:

const found = await client.users.lookup({
    emails: ['a@ryanweiss.net', 'b@ryanweiss.net'],
    ids: [someUserId],
});

Assign / remove users to applications

App access is a per-user grant (user_apps row), separate from identity — these live on client.apps:

const theirApps = await client.apps.listForUser(userId);  // current grants

await client.apps.grantUser(userId, appId);   // idempotent; reactivates revoked
await client.apps.revokeUser(userId, appId);  // blocks THIS app only

Note: apps with auto_grant_on_signup: true re-admit a revoked user on their next login — disable auto-grant for invite-only apps.

Set a user’s roles

Base (platform) roles are a set — setRoles replaces it wholesale:

const roles = await client.users.listRoles(userId);
// → [{ code: 'base_user', … }]

await client.users.setRoles(userId, ['base_user', 'seller']);

Role codes: system_admin, super_admin, seller, buyer, base_user, … — the role model is in auth-server → How it works. Roles take effect on the user’s next token refresh (the server bumps their token-version, so it’s immediate in practice).

Per-organization roles are a different surface — see Organizations.

Sessions, credentials, destructive ops

// session control
const sessions = await client.users.listSessions(userId);
await client.users.terminateSession(userId, sessions[0].id);
await client.users.revokeSessions(userId);          // sign out everywhere

// password override (no current-password check)
await client.users.setPassword(userId, 'TempPass123!');

// impersonation (audited; reason required)
await client.users.impersonate({ targetUserId: userId, reason: 'support ticket #123' });
// … the SDK now acts as the target; client.auth.isImpersonating() === true

// hard delete (system_admin; reason required; refuses org owners)
await client.users.hardDelete({ userId, reason: 'GDPR erasure request' });

User pools

Move a user between identity pools, or tag them into extra pools, via client.pools:

const catalog = await client.pools.list();             // every pool + user counts
const mine    = await client.pools.getForUser(userId); // { namespace, namespaces }

await client.pools.setUserHome(userId, 'partner-portal'); // 409 on email conflict
await client.pools.addUser(userId, 'claimleo');           // tag (idempotent)
await client.pools.removeUser(userId, 'claimleo');        // untag