API

createClient

createClient(options) creates a new TalonAuthClient for the application with appId.

import { createClient } from 'talon-auth'

const appId = '[your-app-id]'
const auth = createClient({ appId })

LoginRequiredError

This error is thrown when the client requires a user login:

import { LoginRequiredError } from 'talon-auth'

try {
  const authorizationHeader = await auth.getHeader()
}
catch (error: unknown) {
  if (error instanceof LoginRequiredError) {
    // Redirect to the login page
    window.location.href = '/login'
  }
  else {
    throw error
  }
}

TalonAuthClient

options

appId - The application id
store (default: IndexedDb) - The storage for device information and access tokens.
loginExpiry (default: 15 minutes) - The time (in seconds) a login request expires. Can not be more than 15 minutes.
deviceId (optional) - Initialize with this device (instead of the default first one)
api (optional) - A custom API URL or TalonApiClient instance

getAccessToken

auth.getAccessToken() returns the access token for the user. Will throw a LoginRequiredError if the user needs to log in for this device.

getHeader

auth.getHeader() returns the Authorization header for the current user in the required form of Bearer <accessToken>.

getLocalUser

auth.getLocalUser() returns the user object from local storage without any network calls. Returns null if no user has signed in yet.

getUser

auth.getUser() returns the most up-to-date user object by fetching a fresh access token first. Returns null if the device has not been logged in yet.

logout

auth.logout() logs the user out but remembers their device so their information is pre-filled the next time they log in.

logoutAndForget

auth.logoutAndForget() logs the user out and deletes this device.

listDevices

auth.listDevices() lists all devices in the store. This can be used to handle account switching.

createDevice

auth.createDevice() creates a new devices and sets it as the currently used device. This will require a user to log in before they can make any requests.

getDevice

auth.getDevice() returns the information (like the device id and linked user) for the current device.

setDevice

auth.setDevice(deviceId) sets the currently used device (usually retrieved from auth.listDevices()).

<talon-login> is a Lit-based web component that handles the full login flow. It can be used directly in HTML or imported in a JavaScript/TypeScript project.

import 'talon-auth/login'

Or via CDN without a build step:

<script type="module" src="https://esm.sh/talon-auth/login"></script>

Place the element in your HTML using your app ID from the Talon dashboard:

<talon-login app-id="[your-app-id]"></talon-login>

The component creates its own auth client internally, shows the login UI when authentication is required, and hides itself once the user is authenticated.

Attributes

app-id (required) - The application ID
api-url (optional) - A custom API base URL
cookie (optional) - Cookie name for storing the access token (see SSR)

Events

login - Fired when a user successfully logs in. event.detail contains the user object.

const loginEl = document.querySelector('talon-login')

loginEl.addEventListener('login', (event) => {
  console.log('Logged in as', event.detail)
})

Methods

The following methods are available on the element: getAccessToken(), getUser(), getHeader(), getLocalUser(), logout(), logoutAndForget(), hide().

getAccessToken(), getUser(), and getHeader() automatically show the login UI when authentication is required and retry after the user logs in successfully. hide() programmatically hides the login UI.

const loginEl = document.querySelector('talon-login')

const token = await loginEl.getAccessToken()
const header = await loginEl.getHeader()
const user = await loginEl.getUser()
await loginEl.logout()
loginEl.hide()

getLoginElement

getLoginElement(selector?) waits for the <talon-login> custom element to be defined and fully initialised before returning it. This is useful in frameworks where the element may not be ready when your code runs. Returns null on the server.

import { getLoginElement } from 'talon-auth'

// Finds the first <talon-login> element
const login = await getLoginElement()

// Or use a CSS selector to find a specific element
const login = await getLoginElement('#my-login')

const user = await login?.getUser()

createVerifier

createVerifier({ appId }) creates a verifier for the application id. It does not need any additional information, works offline and does not make any external requests.

import { createVerifier } from 'talon-auth'

const appId = '[your-app-id]'
const verifier = createVerifier({ appId })

API