Testing

Testing Mode & Dev Teleport

Name: Authon
Author: Authon

Skip OAuth popups during E2E testing and development. Initialize the SDK with a test key (pk_test_) to automatically enable Dev Teleport.

How it works

Generate a test API key (pk_test_...) from your project in the Authon dashboard.

Initialize the SDK with the pk_test_ key in your development environment.

A Dev Teleport section automatically appears at the bottom of the login modal. Enter an email and click Go to sign in instantly without OAuth.

Dev Teleport only works with pk_test_ keys. With pk_live_ keys, the Dev Teleport UI is hidden and the API endpoint returns an error. It never works in production.

SDK Usage

When initialized with a pk_test_ key, the login modal automatically shows Dev Teleport. No additional setup required.

Development setup

import { Authon } from '@authon/js';

// Use pk_test_ key for development
const authon = new Authon(
  'pk_test_your_test_key_here',
  { theme: 'dark' }
);

// Open the login modal — Dev Teleport appears automatically
await authon.openSignIn();

Programmatic Usage

You can also perform test sign-in directly from code without the modal UI.

testing.signIn()

const authon = new Authon('pk_test_xxx', { theme: 'dark' });

// testing is only available with pk_test_ keys
// With pk_live_ keys, authon.testing is undefined
const user = await authon.testing?.signIn({
  email: 'test@example.com',
  nickname: 'Tester'  // optional
});

console.log(user); // { id, email, displayName, ... }

If no user with that email exists in the project, one is automatically created. If the user already exists, a token is issued for the existing user.

E2E Testing Integration

Bypass OAuth popups in E2E testing frameworks like Playwright or Cypress and test with an authenticated state instantly.

tests/auth.setup.ts

import { test } from '@playwright/test';

const API_URL = 'https:0
const TEST_KEY = 'pk_test_your_test_key_here';

test.beforeEach(async ({ page }) => {
  1
  const res = await fetch(6, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': TEST_KEY,
    },
    body: JSON.stringify({ email: 'e2e@test.com' }),
  });
  const { accessToken } = await res.json();

  2
  await page.goto('http://localhost:3000');
  await page.evaluate((token) => {
    localStorage.setItem('authon_token', token);
  }, accessToken);

  // 3. Reload to pick up the auth state
  await page.reload();
});

test('authenticated page works', async ({ page }) => {
  // Already logged in — test your app directly
  await page.goto('/dashboard');
  await page.waitForSelector('[data-testid="user-avatar"]');
});

API Reference

POST/v1/auth/testing/token

Issue an authentication token for a test user instantly. Only available with pk_test_ keys.

Request Headers

x-api-key

Publishable key starting with pk_test_

Request Body

json

{
  "email": "test@example.com",
  "nickname": "Tester"          // optional
}

Response

json

{
  "accessToken": "eyJ...",
  "refreshToken": "rt_...",
  "expiresIn": 900,
  "user": {
    "id": "uuid",
    "email": "test@example.com",
    "displayName": "Tester",
    "emailVerified": true
  }
}

Calling this endpoint with a pk_live_ key returns a 400 error. Generate test keys in Authon Dashboard > Project > API Keys.

Environment Variables

Use separate environment variables for development and production keys.

.env.development

# Development — Dev Teleport enabled
VITE_AUTHON_KEY=pk_test_your_test_key_here

This way, Dev Teleport is automatically enabled or disabled based on the environment — no code changes needed.