Skip to Content
Documentation

Overview

⚡ 12 min read

Integrate passkey login and step-up MFA: create a project in the Console, load the SDK (HTML / CDN or npm), then open modals and verify JWTs on your backend.

Client-side only. The Transcodes SDK runs in the browser only. Do not import or call it from SSR or React Server Components. In Next.js, add 'use client' to any file that uses the SDK.

Console: organization and project

Sign in to Transcodes

Open the Transcodes Console . Creating an account creates an organization (your workspace).

Create a project

  1. Click Create New Project
  2. Enter a project name (required, up to 100 characters) and optional description (up to 200 characters)

Copy your Project ID

After creation, copy the Project ID (e.g. proj_abc123xyz). Use it in the CDN script URL, in init({ projectId }), and in VITE_TRANSCODES_PROJECT_ID / NEXT_PUBLIC_TRANSCODES_PROJECT_ID.

Organization = company/workspace (billing, members). Project = one app or site. Always use the Project ID in SDK code—not an organization ID.

Integration Method

Load Transcodes through the CDN script. For installable PWA/Web App Kit, also add the manifest and sw.js.

MethodWhat you doTypical use
HTML / CDNAdd webworker.js to index.html; add manifest + sw.js only for PWAAuth-only, PWA, copy-paste Dashboard snippets, no npm required

HTML / CDN (default)

Authentication Toolkit Cluster only — passkey login and step-up MFA:

<script src="https://cdn.transcodes.link/YOUR_PROJECT_ID/webworker.js" defer></script>

Quick Start Guides

Passkey-first LoginStep-up MFA

Choose Your Framework

ReactNext.jsVue.jsVanilla JS

Framework Comparison

FrameworkBuild ToolTypeScriptSSRLoad SDKState Management
ReactViteYesNoHTML / CDNContext API
Next.jsNext.jsYesYesCDN script in layoutContext API
Vue.jsViteYesNoHTML / CDNComposables / Pinia
Vanilla JSViteNoNoHTML / CDNClass / Module

Universal Setup

Use the HTML script setup below, then follow the steps.

1. Load the SDK

Script in HTML

Authentication Toolkit Cluster only (Vite):

index.html
<script src="https://cdn.transcodes.link/%VITE_TRANSCODES_PROJECT_ID%/webworker.js" defer></script>

2. Set Environment Variables

Vite (React, Vue, Vanilla):

.env
VITE_TRANSCODES_PROJECT_ID=proj_abc123xyz

Next.js:

.env.local
NEXT_PUBLIC_TRANSCODES_PROJECT_ID=proj_abc123xyz

3. Open Login Modal

CDN (window.transcodes):

const result = await transcodes.openAuthLoginModal({
  projectId: 'proj_abc123xyz',
});
 
if (result.success) {
  const { token, member } = result.payload[0];
  console.log('Logged in as:', member?.email);
}

4. Check Authentication Status

isAuthenticated() is an async method. Always use await

CDN:

const isAuth = await transcodes.token.isAuthenticated();

5. Subscribe to Auth Events

CDN:

const unsubscribe = transcodes.on('AUTH_STATE_CHANGED', (payload) => {
  console.log('Auth state:', payload.isAuthenticated);
});
unsubscribe();

6. Sign Out

CDN: await transcodes.token.signOut();

SDK API Overview

CDN (window.transcodes)

// Token
transcodes.token.getCurrentMember(): Promise<Member | null>
transcodes.token.getAccessToken(): Promise<string | null>
transcodes.token.hasToken(): boolean
transcodes.token.isAuthenticated(): Promise<boolean>  // async!
transcodes.token.signOut(options?: { webhookNotification?: boolean }): Promise<void>
 
// Member
transcodes.member.get(params): Promise<ApiResponse<Member[]>>
 
// Modals
transcodes.openAuthLoginModal(params): Promise<ApiResponse<AuthResult[]>>
transcodes.openAuthConsoleModal(params?): Promise<ApiResponse<null>>
transcodes.openAuthIdpModal(params): Promise<ApiResponse<IdpAuthResponse[]>>
 
// Events
transcodes.on(event, callback): () => void
transcodes.off(event, callback): void
 
// Audit
transcodes.trackUserAction(event, options?): Promise<void>

Available Events

EventDescription
AUTH_STATE_CHANGEDAuthentication state changed (login/logout)
TOKEN_REFRESHEDAccess token was automatically refreshed
TOKEN_EXPIREDToken expired and cannot be refreshed
ERRORSDK error occurred

TypeScript support

Download definitions from the Authentication Kit → Installation Guide in the Console, or:

curl -o transcodes.d.ts https://cdn.transcodes.link/types/transcodes.d.ts

Then point tsconfig.json at your types/ folder (see below).

tsconfig.json
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  },
  "include": ["src", "types"]
}

See each framework guide for full TypeScript setup

Common Patterns

Protected Route Pattern

All frameworks implement a similar protected route pattern:

  1. Check isAuthenticated() (async)
  2. If not authenticated, show login modal
  3. If login cancelled, redirect to home
  4. If authenticated, render protected content

React/Next.js: <ProtectedRoute> component with useEffect Vue: <AuthGuard> component with watch Vanilla JS: init() function with async/await

Auth State Management

FrameworkPatternFile
ReactContext + use() hookAuthContext.tsx
Next.jsContext + 'use client'AuthProvider.tsx
VueComposable / PiniauseAuth.ts / auth.ts
Vanilla JSClass / Moduleauth.js

Common Mistakes

// WRONG: isAuthenticated() is async
if (transcodes.token.isAuthenticated()) { ... }   // CDN
if (isAuthenticated()) { ... }                     // npm
 
// CORRECT
if (await transcodes.token.isAuthenticated()) { ... }   // CDN
if (await isAuthenticated()) { ... }                     // npm
// WRONG
await transcodes.token.logout();
 
// CORRECT
await transcodes.token.signOut();               // CDN
await signOut({ webhookNotification: false });  // npm

Troubleshooting

SDK Not Loading

// Check if SDK is loaded
if (typeof transcodes === 'undefined') {
  console.error('Transcodes SDK not loaded');
}

CORS Errors

Ensure your domain is added to the allowed list in the Transcodes Dashboard :

  • localhost:5173 (Vite dev server)
  • localhost:3000 (Next.js dev server)
  • yourdomain.com (production)

CSP (Content Security Policy)

At minimum, allow the CDN domain for the SDK script. The exact connect-src and frame-src API domains are available in your Transcodes Console  → Authentication Cluster → Installation Guide.

<meta
  http-equiv="Content-Security-Policy"
  content="
  script-src 'self' https://cdn.transcodes.link;
  connect-src 'self' {TRANSCODES_API_DOMAINS};
  frame-src 'self' {TRANSCODES_API_DOMAINS};
"
/>

Replace {TRANSCODES_API_DOMAINS} with the domains listed in your Console.

Production checklist

  1. Allow your domain in the Transcodes Console  (Authentication Kit → Configuration)
  2. HTTPS in production — WebAuthn needs a secure context
  3. CSP — include cdn.transcodes.link and the Transcodes API domains as in CSP above

The SDK only runs on domains you authorize for the project.

Next steps

Last updated on
Introduction