rudder-js-sdk/skills/rudder-web-sdk/reference/auth.md

# Auth — `client.auth`

`AuthService` (source: `src/auth/AuthService.ts`). Player authentication:
device ID login (primary for game clients), custom webhook login, logout, and
auth state observation.

## Methods

```ts
loginWithDevice(options?: LoginWithDeviceOptions): Promise<LoginViaDeviceResponse>
loginWithCustom(options: LoginWithCustomOptions): Promise<LoginViaCustomResponse>
logout(): void
get isAuthenticated(): boolean
onAuthStateChange(listener: AuthStateListener): () => void
```

### `LoginWithDeviceOptions`

```ts
{
  region?: string;    // default 'global'
  language?: string;  // default 'en'
  nickname?: string;  // omitted from the request when not set
}
```

The device ID is auto-generated on first call and persisted in localStorage
(`src/device/DeviceId.ts`). The request also carries the client's
`projectKey`.

### `LoginWithCustomOptions`

```ts
{
  customData: Record<string, unknown>;  // required — forwarded to the project's custom auth webhook
  region?: string;                      // default 'global'
  language?: string;                    // default 'en'
  nickname?: string;
}
```

### Login responses

```ts
interface LoginViaDeviceResponse { accessToken?: string; refreshToken?: string }
interface LoginViaCustomResponse { accessToken?: string; refreshToken?: string }
```

On success both tokens are saved to the client's `TokenStore`, the runtime
starts (domains warmed, scenario engine restored, `player_login` event fired),
and the state flips to `'signed-in'`.

## Environments

A project has two environments, `staging` and `prod`. The SDK key you pass as
`RudderClientOptions.projectKey` belongs to one of them, so the environment is
resolved at login and carried inside the access and refresh tokens; nothing in
the client API takes an environment argument, and a player created in one
environment is invisible in the other. Content released only to `staging` is
empty for a `prod` key and vice versa.

Tokens issued before SDK 2.0.0 carry no environment claim and are rejected with
401. The transport's refresh then fails, clears the token store and emits
`'signed-out'` — log the player in again.

## Auth state

```ts
type AuthState = 'signed-in' | 'signed-out';
type AuthStateListener = (state: AuthState) => void;
```

- `isAuthenticated` is `true` while an access token is present in the token store.
- `onAuthStateChange` fires the listener **immediately** with the current state
  and returns an unsubscribe function.
- `logout()` clears tokens, stops the runtime (sync poll, scenario runs,
  cached domain data), and emits `'signed-out'`.

## Token refresh (automatic, transport level)

Source: `src/transport/request.ts`.

- Every request injects `Authorization: Bearer <accessToken>` when a token exists.
- On 401 the transport does a single-flight refresh against
  `POST /sdk/v1/authorization/refresh` (concurrent 401s share one refresh) and
  retries the original request once.
- If refresh fails, tokens are cleared, `onAuthStateChange` listeners get
  `'signed-out'`, and the request throws `RudderAuthError`.

## TokenStore

```ts
interface TokenStore {
  getAccessToken(): string | null;
  getRefreshToken(): string | null;
  saveTokens(accessToken: string, refreshToken: string): void;
  clear(): void;
}
```

Factories (exported from the package root):

- `createDefaultTokenStore()` — localStorage, with a silent in-memory fallback
  where localStorage is unavailable (SSR, private mode). This is the default
  when `tokenStore` is omitted from `RudderClientOptions`.
- `createLocalStorageTokenStore()` — keys `rudder_access_token` /
  `rudder_refresh_token`.

Provide a custom `TokenStore` via `RudderClientOptions.tokenStore` for other
backends (sessionStorage, cookies).

## Errors

- Constructor: missing `baseUrl`/`projectKey` → `RudderError`,
  `code: 'sdk/invalid-options'`.
- Login failure → `RudderHttpError` (e.g. unknown project key) or
  `RudderNetworkError`.
- Any later request with an expired session → `RudderAuthError` (after the
  refresh attempt above fails).