> ## Documentation Index
> Fetch the complete documentation index at: https://urbackend-mintlify-f636efa8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
signUp(payload: SignUpPayload): Promise<AuthUser>
```

**Example**

```typescript theme={null}
const user = await client.auth.signUp({
  email: 'alice@example.com',
  password: 'secret123',
  username: 'alice_dev',
  name: 'Alice',
});
```

***

## `login`

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

```typescript theme={null}
login(payload: LoginPayload): Promise<AuthResponse>
```

**Returns** `AuthResponse`

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

**Example**

```typescript theme={null}
const { accessToken, user } = await client.auth.login({
  email: 'alice@example.com',
  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.

```typescript theme={null}
refreshToken(refreshToken?: string): Promise<AuthResponse>
```

***

## `me`

Fetch the profile of the currently authenticated user.

```typescript theme={null}
me(token?: string): Promise<AuthUser>
```

***

## `updateProfile`

Update the authenticated user's profile fields.

```typescript theme={null}
updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{ message: string }>
```

**Example**

```typescript theme={null}
await client.auth.updateProfile({ name: 'Alice Smith' });
```

***

## `changePassword`

Change the authenticated user's password.

```typescript theme={null}
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.

```typescript theme={null}
socialStart(provider: 'github' | 'google'): string
```

### `socialExchange`

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

```typescript theme={null}
socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse>
```

**Example**

```typescript theme={null}
// 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.

```typescript theme={null}
publicProfile(username: string): Promise<AuthUser>
```

***

## `logout`

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

```typescript theme={null}
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`.

```typescript theme={null}
// 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();
```