AuthService

pb.auth is an instance of AuthService. It handles all authentication, session tokens, JWT introspection, and admin management.

Types

AuthTokens

{
  access_token: string;
  id_token?: string;
  refresh_token?: string;
  session_id?: string;
  token_type: string;  // 'Bearer'
  expires_in: number;  // seconds
}

AuthUser

{
  sub: string;             // User's unique ID
  email?: string;
  email_verified?: boolean;
  given_name?: string;
  family_name?: string;
  picture?: string;        // Avatar URL
  roles?: string[];
  [key: string]: any;      // Custom claims
}

MFAEnrollResponse

{
  secret: string;
  qr_code_url?: string;     // Scan with authenticator app
  recovery_codes?: string[]; // Store securely — shown only once
}

---

Authentication

signUpWithPassword(email, password, options?)

Register a new user. On success, the user is automatically signed in and tokens are stored.

const result = await pb.auth.signUpWithPassword(
  'jane@example.com',
  'SecurePassword123!',
  {
    given_name: 'Jane',
    family_name: 'Doe',
    user_metadata: { plan: 'free' }, // Stored in user profile
  }
);
// Returns: AuthTokens & { user_id: string }

signInWithPassword(email, password, mfaCode?)

Sign in with email and password. If MFA is enabled, first call returns { mfa_required: true }.

const session = await pb.auth.signInWithPassword('jane@example.com', 'Password123!');

// MFA handling:
if ('mfa_required' in session) {
  const code = await promptUser();
  await pb.auth.signInWithPassword('jane@example.com', 'Password123!', code);
}

Returns: AuthTokens | { mfa_required: true }

signOut()

Revoke the current refresh token and clear the local session.

await pb.auth.signOut();

---

PKCE / Authorization Code Flow

getAuthorizationUrl(state, codeChallenge, scopes?)

Build the authorization URL for redirect-based login (PKCE).

const url = pb.auth.getAuthorizationUrl(state, codeChallenge, 'openid profile email');
window.location.href = url;

exchangeCode(code, codeVerifier)

Exchange an authorization code for tokens (PKCE final step).

const tokens = await pb.auth.exchangeCode(codeFromUrl, storedCodeVerifier);

---

Session Management

getUser()

Fetch fresh user info from the IDP. Updates the cached user.

const user = await pb.auth.getUser();
// Returns: AuthUser

getCachedUser()

Return the locally cached user (no network call). null if not signed in.

const user = pb.auth.getCachedUser();
// Returns: AuthUser | null

getValidAccessToken()

Returns a valid access token, refreshing it first if it’s about to expire. Returns null if not authenticated.

const token = await pb.auth.getValidAccessToken();

getTokens()

Returns the current raw tokens (may be expired).

const tokens = pb.auth.getTokens();
// Returns: AuthTokens | null

setSession(tokens)

Manually set tokens (e.g., after an OAuth callback).

pb.auth.setSession({ access_token: '...', refresh_token: '...', token_type: 'Bearer', expires_in: 3600 });

refreshSession()

Manually trigger a token refresh.

const newTokens = await pb.auth.refreshSession();

isAuthenticated()

Check if the user is currently signed in (token exists in memory).

if (pb.auth.isAuthenticated()) { ... }

---

Password Management

resetPassword(email)

Request a password reset email. No error thrown if email doesn’t exist (security best practice).

await pb.auth.resetPassword('user@example.com');

confirmResetPassword(token, newPassword)

Complete a password reset using the token from the email link.

await pb.auth.confirmResetPassword(tokenFromUrl, 'NewPassword456!');

updatePassword(currentPassword, newPassword)

Change password for the currently signed-in user. Requires the current password.

await pb.auth.updatePassword('CurrentPass123!', 'NewPass456!');

---

Email Verification

requestEmailVerification()

Send (or resend) a verification email to the current user.

await pb.auth.requestEmailVerification();

confirmEmailVerification(token)

Confirm email verification using the token from the verification email.

await pb.auth.confirmEmailVerification(tokenFromUrl);

---

MFA

pb.auth.mfa.enroll()

Enroll the current user in TOTP-based MFA. Returns a QR code URL for authenticator apps and recovery codes.

const { qr_code_url, recovery_codes } = await pb.auth.mfa.enroll();
// Display qr_code_url to user for scanning
// Store recovery_codes securely — shown only once!

pb.auth.mfa.verify(code)

Activate MFA by verifying the first TOTP code.

await pb.auth.mfa.verify('123456');

pb.auth.mfa.disable()

Disable MFA for the current user.

await pb.auth.mfa.disable();

---

JWT Introspection (Local — No Network)

All of these read from the cached JWT without making any network requests.

getRoles()

const roles = pb.auth.getRoles(); // string[]

getPermissions()

const perms = pb.auth.getPermissions(); // string[]

hasRole(role)

pb.auth.hasRole('admin')           // boolean

hasAnyRole(...roles)

Returns true if the user has at least one of the specified roles.

pb.auth.hasAnyRole('admin', 'moderator')

hasPermission(permission)

pb.auth.hasPermission('content.publish')

hasAllPermissions(...permissions)

Returns true only if the user has all specified permissions.

pb.auth.hasAllPermissions('content.read', 'content.write')

hasAnyPermission(...permissions)

Returns true if the user has at least one of the specified permissions.

pb.auth.hasAnyPermission('content.read', 'content.admin')

---

Admin: User Management

All management methods require the caller to have an admin role in their JWT.

listUsers()

const users = await pb.auth.listUsers();

getUserById(userId)

const user = await pb.auth.getUserById('user-uuid');

updateUser(userId, data)

await pb.auth.updateUser(userId, {
  email_verified: true,
  status: 'active',          // 'active' | 'disabled'
  given_name: 'Jane',
  family_name: 'Doe',
  roles: ['admin', 'editor'],
});

---

Admin: Role Management

listAllRoles()

const roles = await pb.auth.listAllRoles();

createRole(name, description?)

await pb.auth.createRole('editor', 'Can create and edit content');

deleteRole(name)

await pb.auth.deleteRole('editor');

assignRoles(userId, roles)

Replaces the user’s current roles with the given list.

await pb.auth.assignRoles(userId, ['admin', 'editor']);

---

Admin: Permission Management

listAllPermissions()

const perms = await pb.auth.listAllPermissions();

createPermission(key, description?)

await pb.auth.createPermission('content.publish', 'Publish articles to production');

deletePermission(key)

await pb.auth.deletePermission('content.publish');

setRolePermissions(roleName, permissions)

Replace the permission set for a role.

await pb.auth.setRolePermissions('editor', ['content.read', 'content.write']);

getRolePermissions(roleName)

const perms = await pb.auth.getRolePermissions('editor'); // string[]

setUserPermissions(userId, allow, deny?)

Set user-specific permission overrides (bypasses role-based logic).

await pb.auth.setUserPermissions(userId, ['reports.view'], ['billing.access']);

getUserPermissions(userId)

const { allow_permissions, deny_permissions } = await pb.auth.getUserPermissions(userId);