> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/guides/authentication/authenticate-your-user.md).

# Authenticate your user

This guide wires up login, logout, and a signed-in UI in your app. It does **not** cover product gating — for subscriptions, see [monetizing with subscriptions](/guides/subscriptions/monetize-with-subscriptions.md); for time-based billing, see [charging for time-based sessions](/guides/time-based-billing/charge-for-time-based-sessions.md).

***

## 1. Install and initialize the SDK

If you haven't yet, install `@tiun/sdk` and initialize it. The [Quickstart](/quickstart.md) has the full install commands; here's the minimal init:

```javascript
import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
});
```

***

## 2. Add a login button

`tiun.login()` opens the tiun login overlay where the user enters their email and verifies via phone OTP. The full login flow — what the overlay does and how the session is persisted — is covered in [Authentication / How it works](/reference/authentication/how-it-works.md) in Reference.

```javascript
function onClickLogin() {
  tiun.login();
}
```

After a successful login, `userChange` fires with `event: 'login'`.

***

## 3. Add a logout button

`tiun.logout()` clears the session on the current device.

```javascript
function onClickLogout() {
  tiun.logout();
}
```

After logout, `userChange` fires with `event: 'logout'` and `user` is `null`.

***

## 4. React to user state changes

Listen to `userChange` to keep your UI in sync. The handler fires on session restore, login, logout, and anytime user state updates — so you don't need to poll.

```javascript
tiun.on('userChange', (data) => {
  if (!data.isAuthenticated) {
    showLoginButton();
    return;
  }

  showLogoutButton(data.user.email);
});
```

`data.user` is the **user object** — `null` when nobody is signed in, otherwise it carries `userId`, `email`, and (for subscription users) `productAccess`. See [User object](/reference/authentication/user-object.md) in Reference for the full shape and when each field is populated.

***

## 5. Session restore is automatic

When a returning user loads your app, tiun restores their session automatically. `userChange` fires with `event: 'init'` and the same payload as above — so the handler from step 4 covers this case too.

***

## Full example

```javascript
import { tiun } from '@tiun/sdk';

tiun.on('userChange', (data) => {
  if (!data.isAuthenticated) {
    showLoginButton();
    return;
  }

  showLogoutButton(data.user.email);
});

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
});

function login() {
  tiun.login();
}

function logout() {
  tiun.logout();
}
```

***

If your backend serves protected data, you'll also want to verify the user's identity server-side — see [server-side authentication verification](/guides/authentication/verify-server-side.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tiun.io/guides/authentication/authenticate-your-user.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.