> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cskn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Get the signed-in user in a browser and inside a native shell with one hook.

Your app never handles passwords or OAuth itself. The platform signs the user in, and `useBridgeAuth` makes the result available to your code and to every API call the SDK makes.

## useBridgeAuth

Call it **once**, near the root of your app.

```tsx theme={null}
import { useBridgeAuth, useUser } from '@cskn/sdk';

function Root() {
  const { token, user, isReady } = useBridgeAuth();
  const { data: profile } = useUser({ enabled: isReady && !!token });

  if (!isReady) return <Splash />;
  if (!token) return <SignIn />;
  return <Home profile={profile} />;
}
```

<ResponseField name="isReady" type="boolean">
  `true` once the hook knows whether there is a user. Wait for it before calling authenticated endpoints, or the first requests go out without credentials and fail with `401`.
</ResponseField>

<ResponseField name="token" type="string | null">
  Non-null when a user is signed in. Treat it as a flag; the SDK attaches credentials to requests for you.
</ResponseField>

<ResponseField name="user" type="{ sub?, name?, email?, picture?, username? } | null">
  Basic identity of the signed-in user, available without a network round trip.
</ResponseField>

### How it resolves

| Surface | Source | Result |
| - | - | - |
| Browser, signed in | `window.cskn.auth` from the host | Ready at once. API calls go through your origin's `/api` proxy, which forwards the session cookie. |
| Browser, signed out | — | Ready at once with `token: null`. |
| Native shell | `auth` message over the bridge | Ready when the shell answers. The bearer token is attached to every SDK request. |

## Sign in and sign out

Never build the auth URLs yourself; take them from the SDK.

```tsx theme={null}
import { login, logout, logoutUrl } from '@cskn/sdk';

login();                       // back to the current page after sign-in
login('https://my-app.cskn.app/welcome');

logout();                      // back to the current origin
logout({ returnTo: 'https://…', allSessions: true });
```

<ParamField path="returnTo" type="string">
  Where to send the user after logout. Defaults to the current origin.
</ParamField>

<ParamField path="allSessions" type="boolean" default="false">
  End every cskn session on this device, not just this app's. Adds `session=all` to the link.
</ParamField>

`logoutUrl(options)` returns the same link without navigating. Use it when something else has to follow the link, for example a confirmation dialog. @cskn/ui ships one: [`LogoutConfirm`](/ui/components/overlays#logoutconfirm).

## Lower-level API

The hook is built from functions you can use outside React:

```ts theme={null}
import { initAuth, requestToken, getToken, getUser, onTokenChange, onUserChange } from '@cskn/sdk';

const stop = initAuth();               // listen for the shell's auth messages; returns cleanup
const unsubscribe = onTokenChange((t) => console.log('token', t));
requestToken();                        // ask the shell to resend the current token
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.