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

# Authentication

> User authentication modes and bot protection

The Voltai Widget supports different authentication modes to fit your use case.

## Guest mode

Guest mode lets visitors use the chat without signing in. This is useful for public-facing support widgets where you want to minimize friction.

Enable it with the `enableGuestUser` option:

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true
});
```

When guest mode is enabled:

* Users start chatting after a quick verification step the first time they open the widget or trigger a programmatic chat
* A temporary session is created automatically
* Chat history persists across page refreshes (stored locally)
* Guest users are limited to **5 questions** before being prompted to sign in

<Note>
  Guest sessions are anonymous and have a 5-question limit. After reaching this limit, users will need to log in to continue chatting.
</Note>

## Bot protection with hCaptcha

To protect against automated abuse, the widget integrates with [hCaptcha](https://www.hcaptcha.com/). When enabled, guest users complete a captcha challenge inside the widget before their guest session is created.

This happens when:

* Guest mode is enabled (`enableGuestUser: true`)
* hCaptcha is configured on your backend
* The user opens the widget or a programmatic `sendChat()` call needs a guest session

The widget keeps the launcher visible at all times. If verification fails, users can retry from the open panel without losing access to the launcher.

<Tip>
  hCaptcha configuration is handled server-side. Contact your administrator if you need to enable or adjust captcha settings.
</Tip>

## Authenticated users

For applications where users have accounts, the widget supports popup-based authentication. This allows:

* Users to sign in with their existing credentials
* Conversations tied to their account
* Chat history synced across devices
* Personalized responses based on user context
* Unlimited questions (no 5-question limit)

## Auth0 Connection

If you have a specific login method configured for your organization, you can specify which connection to use:

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  authConnection: 'EXAMPLE'
});
```

When `authConnection` is set, users are directed to that specific login method. When omitted, it displays its standard Login Widget with all available options.

## Default organization selection

If authenticated users can belong to multiple organizations, you can tell the widget which organization to prefer after login:

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  authConnection: 'EXAMPLE',
  defaultOrgName: 'Acme'
});
```

When `defaultOrgName` is set, the widget looks for a case-insensitive match against the user's available organization names. If no match is found, it falls back to the first available organization automatically.

## How authentication works

1. **Widget loads** — The SDK initializes and checks for existing sessions
2. **Session check** — If a valid token exists locally, it's restored
3. **Open or send** — If no session exists and guest mode is enabled, opening the widget or calling `sendChat()` shows the verification step
4. **Guest session** — After captcha succeeds, a guest token is fetched and stored locally for future visits
5. **Continue chatting** — The chat UI appears and any queued `sendChat()` request is submitted automatically

## Programmatic authentication

You can check authentication status and trigger login programmatically from your code.

### Waiting for auth state

The widget exposes auth methods immediately, but auth restoration still happens asynchronously after `Voltai.load()`. Use `onAuthReady`, `auth:ready`, or `voltai.isAuthReady()` when you need to make a decision based on the settled auth state before opening the widget.

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true,
  onAuthReady: ({ isLoggedIn, isGuest }) => {
    console.log('Auth initialized', { isLoggedIn, isGuest });
  }
});
```

### Checking login status

Use `isLoggedIn()` to check if a user is signed in (returns `false` for guest users). If you care about startup timing, check `isAuthReady()` first:

```javascript theme={null}
if (!voltai.isAuthReady()) {
  console.log('Still restoring auth state');
} else if (voltai.isLoggedIn()) {
  console.log('User is signed in with a full account');
} else {
  console.log('User is a guest or not logged in');
}
```

### Triggering login

Prompt users to sign in. `voltai.login()` is safe to call before the widget is opened:

```javascript theme={null}
if (!voltai.isLoggedIn()) {
  await voltai.login();
}
```

### Logging out

```javascript theme={null}
await voltai.logout();
```

### Listening for auth changes

Subscribe to authentication events to react when users log in or out:

```javascript theme={null}
voltai.on('auth:ready', ({ isLoggedIn, isGuest }) => {
  console.log('Auth initialized', { isLoggedIn, isGuest });
});

voltai.on('auth:login', (payload) => {
  if (payload.isGuest) {
    console.log('Guest user logged in');
  } else {
    console.log('User signed in');
  }
});

voltai.on('auth:logout', () => {
  console.log('User logged out');
});
```

### Example: Custom login button

```html theme={null}
<button id="login-btn">Sign In</button>

<script>
  const voltai = Voltai.load({
    apiKey: 'your-api-key',
    enableGuestUser: true,
    onAuthReady: () => {
      console.log('Auth initialization complete');
    }
  });

  document.getElementById('login-btn').onclick = async () => {
    if (!voltai.isLoggedIn()) {
      await voltai.login();
    }
  };
</script>
```

### Example: Check auth before opening the widget

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true,
  onAuthReady: async ({ isLoggedIn }) => {
    if (!isLoggedIn) {
      await voltai.login();
    }
  }
});
```

In this flow:

* `onReady` is too early for auth decisions because it only means the widget mounted.
* `onAuthReady` runs after auth restoration has settled.
* If the widget is later opened while the visitor still has no session and `enableGuestUser` is enabled, the guest captcha flow still happens inside the widget.

## Handling authentication errors

If verification or authentication fails, the widget button still remains available and the open panel shows a retry path.

Common issues:

* **Invalid API key** — Verify your API key is correct
* **hCaptcha failure** — May occur if the user's browser blocks the captcha script
* **Network errors** — Check connectivity to the backend

## Security considerations

* **API keys** are visible in client-side code. They're scoped to your domain and only allow widget operations.
* **Guest tokens** are short-lived and automatically refresh.
* **hCaptcha** adds a layer of protection against automated abuse.

For sensitive applications, authenticated mode (coming soon) provides stronger user verification.