Authentication

The SDK supports three authentication modes. Choose the one that fits your application.

Built-in Auth (Default)

By default, the widget shows a login screen with email/password fields, registration, and password reset. No configuration needed beyond the API URL.

<saytv-chat app-id="your-app-id"></saytv-chat>

The built-in auth UI handles:

• Email/password login
• New user registration
• Password reset (forgot password)
• Email verification flow

User sessions are persisted during the page session, so users stay logged in within the same tab.

External JWT Token

If your application already has a logged-in user, pass their JWT token to the widget. The SDK exchanges it for a SayTV session token automatically.

<saytv-chat
  app-id="your-app-id"
  auth-token="eyJhbGciOiJIUzI1NiIs..."
  built-in-auth="false"
></saytv-chat>

Once authenticated, the SayTV session is stored for the duration of the page session.

Updating the Token

The auth-token attribute is reactive. Update it at any time:

const chat = document.querySelector('saytv-chat');
chat.setAttribute('auth-token', newToken);

Rapid token changes are handled efficiently to prevent unnecessary re-authentication.

Usernames

If your tenant is configured with a username claim, the SDK maps it onto the SayTV account when that account is first created, and syncs it on every subsequent re-authentication. Renaming a user is therefore usually just a matter of issuing a token with the new claim.

Two things to know:

• If the claimed name is already held by someone else, the sync is skipped and the user keeps their current name. Authentication still succeeds — a name clash never locks anyone out of chat. You will not see an error.
• To rename with a definitive success/failure answer, call setUsername() instead. It rejects with a 422 and a field-level reason when the name is taken, too short, or blocked by moderation.

Usernames are unique per tenant. A name held by a deleted account is released and becomes available again.

React

<SayTVChat
  appId="your-app-id"
  authToken={userToken}
  builtInAuth={false}
/>

Or use the hook:

const { setToken } = useSayTVChat();
setToken(newToken);

Vue

<SayTVChat
  app-id="your-app-id"
  :auth-token="userToken"
  :built-in-auth="false"
/>

Or use the composable:

const { setToken } = useSayTVChat();
setToken(newToken);

Guest Mode (Read-Only)

Set built-in-auth="false" and pass no auth-token to let visitors read the chat without signing in. The widget skips the login screen and goes straight to the episodes list.

<saytv-chat
  app-id="your-app-id"
  built-in-auth="false"
></saytv-chat>

Every SayTV endpoint requires a bearer token, so "no sign-in" does not mean "no session". On start-up the widget calls POST /guest/user and gets a token for a throwaway guest account, which is what makes browsing work. The token lives in sessionStorage for the tab, and the guest account is pruned once it has been idle for a week.

Guests can read episodes, chat history, the leaderboard and reactions. They cannot post, react, vote in polls or quizzes, edit a profile, or use friends — the composer is replaced with a prompt to sign in, the Friends tab is hidden from the tab bar, and the API refuses those routes with a 403.

WARNING

Read-only enforcement is a tenant setting. The widget always hides write controls from guests, but the API only rejects guest writes when the GuestRouteAccess feature is enabled for your tenant. Ask SayTV support to confirm it is on before relying on guest mode in production.

To upgrade a guest to a real user, set auth-token (or re-enable built-in auth) — the widget swaps the guest session for the authenticated one. Guest sessions are anonymous and disposable: nothing carries over.

Authentication Events

Listen for auth-related events on the widget element:

const chat = document.querySelector('saytv-chat');

chat.addEventListener('stv:user-login', (e) => {
  console.log('User logged in:', e.detail);
});

chat.addEventListener('stv:user-logout', (e) => {
  console.log('User logged out');
});

See Events Reference for all available events.

Session Behavior

• Sessions persist during a single page session (tab/window)
• Closing the tab clears the session
• Calling logout clears all stored tokens and state