@authrspace/sdk

Framework-agnostic JavaScript and TypeScript SDK for Authr hosted authentication, headless authentication, sessions, profiles, and product-intent flows.

Install

npm install @authrspace/sdk

See the changelog for release history.

Quick start

Create a client with the public client ID issued to your application, then open the hosted authentication experience:

import { AuthrClient } from '@authrspace/sdk'

const authr = new AuthrClient({
  clientId: 'YOUR_PUBLIC_CLIENT_ID',
})

authr.signIn()

Authr handles sign-up, email verification, and profile setup inside the hosted experience. The SDK works with vanilla JavaScript, TypeScript, React, Vue, Svelte, Next.js, Nuxt, and other browser applications.

Configuration

const authr = new AuthrClient({
  clientId: 'YOUR_PUBLIC_CLIENT_ID',
  env: 'production',
  persistSession: true,
  locale: 'en',
})

• clientId is required and identifies the integrating application.
• env selects the deployment: production (default), development, or local.
• persistSession defaults to true. Set it to false to disable SDK-managed browser persistence.
• locale is an optional BCP-47 language tag for the hosted UI.

Hosted authentication

signIn() opens Authr's hosted sign-in and sign-up flow:

authr.signIn()

Other hosted product flows are available through the same client:

authr.joinWaitlist('OPTIONAL_REFERRAL_CODE')
authr.reserveUserName()
authr.NewsletterSubscribe()

The bound methods can be passed directly to DOM or framework event handlers:

document
  .querySelector('#sign-in')
  ?.addEventListener('click', authr.signIn)

Events

Subscribe with on(). It returns an unsubscribe function:

const unsubscribe = authr.on('authenticated', ({ user, token }) => {
  console.log('Signed in:', user)
  console.log('Access token:', token)
})

unsubscribe()

Available events:

• open — the hosted modal opened.
• close — the hosted modal closed.
• authenticated — { user, token } after successful hosted authentication.
• session — { isAuthenticated, user, token } when local session state changes.
• newsletterState — { subscribed: boolean } after newsletter state is reported by the hosted UI.
• error — a string describing a hosted UI or authentication error.

Sessions

A successful authentication returns an app-scoped access token and user data. Access tokens last approximately 15 minutes. Persisted refresh sessions last up to 30 days and are refreshed automatically when possible.

const session = authr.getSession()

if (session.isAuthenticated) {
  console.log(session.user)
}

Restore a persisted session when your application starts:

const restored = await authr.restoreSession()

if (restored) {
  console.log('Session restored')
}

The client also exposes a reactive shared state through authr.state:

const { isAuthenticated, user, token } = authr.state

Clear the current session when the user signs out:

authr.clearSession()

Persisted sessions are stored in browser localStorage under an app-specific key. Do not expose refresh tokens to your server logs or analytics systems.

Headless authentication

Use authr.sdk when your application owns the authentication screens and needs Authr's authentication engine without the hosted UI.

A typical passwordless OTP flow looks like this:

const started = await authr.sdk.signin({
  email: '[email protected]',
})

const verified = await authr.sdk.verify({
  code: 'ABC123',
})

const user = await authr.sdk.getMe()
console.log(user.data)

Use signup() instead of signin() for registration:

await authr.sdk.signup({
  email: '[email protected]',
})

Available headless operations include:

• signin({ email }) and signup({ email }) — start an OTP transaction.
• verify({ code }) — verify the pending OTP and store the token pair.
• resendOtp() — resend the pending transaction's OTP.
• refresh(refreshToken) — rotate the session tokens.
• getToken() and getRefreshToken() — read stored credentials.
• getMe() — retrieve the authenticated user and profile.
• restoreSession() — restore the current headless session.
• signout(refreshToken?) — revoke the remote refresh session and clear local credentials.
• createProfile(input) and updateProfile(input) — manage the user's profile.
• generateUsername({ full_name }) — generate a username suggestion.
• checkUsernameAvailability(username) — check username availability.
• generateAvatarUrl(identifier, options?) — generate an avatar URL.

Headless responses use this shape:

{
  data: ..., 
  meta: { request_id: '...' }
}

Expired access tokens are refreshed automatically when a refresh token is available. HTTP failures are thrown as AuthrHeadlessError with message, status, and body properties.

TypeScript

The package includes bundled type declarations and exports public types such as AuthrConfig, AuthrUser, AuthrState, AuthrIntent, ModalOptions, and the headless API input and response types.

Environments

const authr = new AuthrClient({
  clientId: 'YOUR_PUBLIC_CLIENT_ID',
  env: 'development',
})

Use development for the hosted development deployment and local when running the Authr UI and API locally. Production applications should use the default production environment.