Auth

Manage user accounts, sessions, and social authentication with the SDK auth module.

You can access auth methods via client.auth. When you call login(), signUp(), or refreshToken(), the module stores the accessToken and refreshToken and uses them for subsequent authenticated requests such as me() or updateProfile().

In the browser, the SDK persists the access token in localStorage under ub_auth_token and the refresh token under ub_refresh_token. On the next page load, both values are read back automatically. Login, signup, and refresh calls send x-refresh-token-mode: header (and, for refresh, x-refresh-token) so cross-domain setups work without relying on HTTP-only cookies.

signUp

Create a new user account.

signUp(payload: SignUpPayload): Promise<AuthUser>

Example

const user = await client.auth.signUp({
  email: '[e-mail]',
  password: 'secret123',
  username: 'alice_dev',
  name: 'Alice',
});

---

login

Authenticate an existing user. The returned accessToken is stored internally.

login(payload: LoginPayload): Promise<AuthResponse>

Returns AuthResponse

interface AuthResponse {
  accessToken?: string;
  token?: string; // Alias for accessToken (deprecated)
  refreshToken?: string;
  expiresIn?: string;
  userId?: string;
  user?: AuthUser;
}

Example

const { accessToken, user } = await client.auth.login({
  email: '[e-mail]',
  password: 'secret123',
});

---

refreshToken

Rotate the current access token.

• Browser: Call without arguments. The SDK reads the refresh token stored in localStorage under ub_refresh_token and sends it in the x-refresh-token header. If no stored token is found, the request falls back to credentials: 'include' so any legacy HTTP-only cookie is still honored.
• Mobile/Node: Pass the refreshToken string manually. The SDK sends it in the x-refresh-token header.

The returned refreshToken, if present, is persisted automatically for the next call.

refreshToken(refreshToken?: string): Promise<AuthResponse>

---

me

Fetch the profile of the currently authenticated user.

me(token?: string): Promise<AuthUser>

---

updateProfile

Update the authenticated user’s profile fields.

updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{ message: string }>

Example

await client.auth.updateProfile({ name: 'Alice Smith' });

---

changePassword

Change the authenticated user’s password.

changePassword(payload: ChangePasswordPayload, token?: string): Promise<{ message: string }>

---

Social auth

urBackend supports OAuth via GitHub and Google.

socialStart

You receive a URL to initiate the OAuth flow. Redirect your user’s browser to this URL.

socialStart(provider: 'github' | 'google'): string

socialExchange

Exchange the rtCode received at your callback URL for a refresh token.

socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse>

Example

// At your /auth/callback page
const urlParams = new URLSearchParams(window.location.search);
const rtCode = urlParams.get('rtCode');
const token = new URLSearchParams(window.location.hash.slice(1)).get('token');

if (!token || !rtCode) {
  throw new Error('Missing required OAuth callback parameters');
}

const { refreshToken } = await client.auth.socialExchange({ token, rtCode });

---

Account verification

Use these methods to handle email OTP flows.

Method	Description
verifyEmail(payload)	Verify an account using the OTP sent to email.
resendVerificationOtp(payload)	Request a new verification OTP.
requestPasswordReset(payload)	Start the “forgot password” flow.
resetPassword(payload)	Complete password reset using an OTP.

---

publicProfile

Fetch a public-safe profile for any user by their username. This does not return sensitive fields like email or provider IDs.

publicProfile(username: string): Promise<AuthUser>

---

logout

Call this to revoke your current session on the server and clear the local token.

logout(token?: string): Promise<{ success: boolean; message: string }>

---

Manual token management

If you need to manage tokens manually (for example, after social auth or when restoring a session in a non-browser environment), you can use these helper methods:

• getToken(): Returns the current access token. In the browser, falls back to localStorage.ub_auth_token when the in-memory value is unset.
• setToken(token?, refreshToken?): Manually set the access token and, optionally, the refresh token. In the browser, both values are also written to localStorage (ub_auth_token and ub_refresh_token). Passing undefined for the access token clears it.
• getRefreshToken(): Returns the current refresh token. In the browser, falls back to localStorage.ub_refresh_token.
• setRefreshToken(token?): Manually set or clear the refresh token. In the browser, this also writes to localStorage.ub_refresh_token.

// Restore a session (for example, after socialExchange returns a refresh token)
client.auth.setToken(accessToken, refreshToken);

// Later, hand the access token to a custom fetch call
const token = client.auth.getToken();