# JavaScript SDK (browser)

`@ohauthcat/js` signs your end users in from a single-page app through the [hosted login](/user-management/hosted-login/), using only your publishable key. It has no runtime dependencies. Its method names match the [React Native SDK](/sdks/react-native/).

## Install

```sh
npm install @ohauthcat/js
```

## Create the client

`new OhAuthCatClient(options)` takes:

| Option        | Meaning                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `loginOrigin` | The login host, `https://login.ohauthcat.com`.                                                                        |
| `clientId`    | The environment's publishable key (`pk_…`), or an OAuth client ID in OAuth mode.                                      |
| `redirectUri` | A registered redirect URI, matched exactly.                                                                           |
| `mode`        | `{ kind: "user_management" }` (default) or `{ kind: "oauth", environmentId }` for [connected apps](/oauth-provider/). |
| `scopes`      | Optional scopes to ask for.                                                                                           |

## Sign in

- `signIn({ organizationId, prompt, returnTo })` navigates to the hosted login with PKCE (S256), `state` and `nonce`. `prompt` is `login`, `consent` or `none`; `returnTo` is a same-origin path. `createSignInUrl()` returns the URL without navigating.
- On the redirect page, `isRedirectCallback()` tells you the page is a callback, and `handleRedirectCallback()` checks the exact redirect URI, `state`, the `iss` parameter and the ID token, exchanges the code and returns `{ user, returnTo }`.
- `getAccessToken()` returns a valid access token, refreshing once for concurrent callers; `refresh()` forces a refresh. A reused refresh token ends the session.
- `getUser()`, `isSignedIn()`, `getState()` and `subscribe(listener)` read the signed-in state; `switchOrganization(id)` signs in again into another organization.
- `signOut({ returnTo })` clears the session in every tab and revokes the refresh token where the issuer offers revocation.

Send the access token to your API as a bearer token and verify it on the server against the JWKS (see [sessions and tokens](/user-management/sessions-and-tokens/)).

## Token storage

Tokens stay in memory only, never in localStorage or cookies. A reload starts signed out; `signIn()` then completes without a prompt while the hosted login session is alive. Only the short-lived state of a started sign-in is kept in sessionStorage (single use, 10 minutes). Sign-out is broadcast to other tabs without tokens in the messages.

## Errors

Every error is an `OhAuthCatError` (check with `isOhAuthCatError`). Its `code` is a server [error code](/errors/) or a client-side kind such as `state_mismatch`, `issuer_mismatch`, `redirect_mismatch`, `invalid_id_token`, `not_signed_in` or `network`.

## Admin portal embed

`attachPortalEmbed(iframe, { url, allowedOrigins, theme, locale, onReady, onResize, onComplete, onClose, onSessionExpired, onError })` shows a [portal link](/hosted-portal/portal-links/) your backend created in an iframe. Messages are typed and checked against the allowed origins, the frame height follows the portal, and no token is ever sent in a message. Turn on [portal embedding](/hosted-portal/#embed-the-portal-in-your-app) for the environment first.
