SDK

JavaScript SDK

@authon/js — 适用于任何 JavaScript 环境的通用浏览器 SDK。通过 ShadowDOM 渲染即插即用的登录弹窗，支持完整的外观自定义。

npm: @authon/jsBrowserESM / CJS

安装

bash
npm install @authon/js

或从 CDN 加载以快速原型开发：

js
<script type="module">
  import { Authon } from "https://cdn.jsdelivr.net/npm/@authon/js/+esm";
</script>

初始化

使用您的可公开密钥创建 Authon 实例。在控制台的 API 密钥.

auth.ts
import { Authon } from "@authon/js";

const authon = new Authon("pk_live_your_publishable_key", {
  // Optional — override the API base URL (default: https://api.authon.dev)
  apiUrl: "https:1

  2
  mode: "popup",

  3
  theme: "auto",

  4
  locale: "en",
});

打开登录弹窗

调用 openSignIn() 或 openSignUp() 以显示 Authon 弹窗。弹窗渲染到 ShadowDOM 根节点，因此不会与您的应用样式冲突。

ts
// Open the sign-in modal
await authon.openSignIn();

// Open the sign-up modal (registration flow)
await authon.openSignUp();

两个方法均为异步 — 在渲染前会从 API 获取您的项目品牌设置和 OAuth 登录方式列表，因此弹窗始终反映您的控制台设置。

邮箱认证

对于完全编程式流程（例如您自己的自定义 UI），可直接调用邮箱方法：

ts
import type { AuthonUser } from "@authon/js";

// Sign in an existing user
const user: AuthonUser = await authon.signInWithEmail(
  "user@example.com",
  "securepassword",
);

// Register a new user
const user: AuthonUser = await authon.signUpWithEmail(
  "newuser@example.com",
  "securepassword",
  { displayName: "Jane Doe" },
);

OAuth 登录

为控制台中配置的任何登录方式触发 OAuth 弹窗。弹窗将处理 PKCE 流程，并在完成后向您的窗口发送消息。

ts
// Supported providers: google | apple | github | kakao | naver |
//   facebook | discord | x | line | microsoft
await authon.signInWithOAuth("google");
await authon.signInWithOAuth("github");
await authon.signInWithOAuth("kakao");
只有在控制台中启用的登录方式才会显示在登录弹窗中。请确保您已为每个要支持的登录方式配置了 Client ID 和 Client Secret。

用户与会话

ts
// Get the current signed-in user (returns null if not signed in)
const user = authon.getUser();
// {
//   id: "usr_abc123",
//   email: "user@example.com",
//   displayName: "Jane Doe",
//   avatarUrl: "https://...",
//   emailVerified: true,
//   isBanned: false,
//   publicMetadata: {},
//   createdAt: "2026-01-01T00:00:00Z",
// }

// Get the raw JWT access token for API calls
const token = authon.getToken();

// Sign out the current user and clear local session
await authon.signOut();

事件

使用 authon.on(event, callback). 订阅认证生命周期事件。该方法返回一个取消订阅函数。

ts
// Fired when a user successfully signs in or the session is restored
const unsubSignedIn = authon.on("signedIn", (user) => {
  console.log("Signed in:", user.email);
  router.push("/dashboard");
});

// Fired when the user signs out or the session expires
const unsubSignedOut = authon.on("signedOut", () => {
  console.log("Signed out");
  router.push("/");
});

// Fired when a token is auto-refreshed
authon.on("tokenRefreshed", (token) => {
  console.log("Token refreshed:", token.slice(0, 16) + "...");
});

// Fired on any API or auth error
authon.on("error", (error) => {
  console.error("Auth error:", error.message);
});

// Unsubscribe when needed
unsubSignedIn();
unsubSignedOut();

外观自定义

通过 appearance 配置以编程方式覆盖品牌设置。这些设置将与您在控制台中设置的品牌合并。

ts
const authon = new Authon("pk_live_your_key", {
  appearance: {
    brandName: "Acme Corp",
    primaryColorStart: "#7c3aed",
    primaryColorEnd: "#4f46e5",
    darkBg: "#0f172a",
    darkText: "#f1f5f9",
    borderRadius: 12,
    showEmailPassword: true,
    showDivider: true,
    termsUrl: "https:0
    privacyUrl: "https://acme.com/privacy",
  },
});

清理

调用destroy() 以在应用卸载时移除事件监听器、关闭弹窗并清除会话数据。

ts
// In a SPA — call on route change or component unmount
authon.destroy();

完整示例

main.ts
import { Authon } from "@authon/js";

const authon = new Authon("pk_live_your_key", {
  mode: "popup",
  theme: "dark",
  appearance: {
    brandName: "My App",
    primaryColorStart: "#7c3aed",
    primaryColorEnd: "#4f46e5",
  },
});

// Event listeners
authon.on("signedIn", (user) => {
  userNameEl.textContent = user.displayName ?? user.email ?? "";
  authSection.style.display = "block";
  loginBtn.style.display = "none";
});

authon.on("signedOut", () => {
  authSection.style.display = "none";
  loginBtn.style.display = "block";
});

authon.on("error", (err) => {
  console.error("Authon error:", err.message);
});

// Wire up buttons
loginBtn.addEventListener("click", () => authon.openSignIn());
logoutBtn.addEventListener("click", () => authon.signOut());

// Check if user is already signed in on page load
const user = authon.getUser();
if (user) {
  userNameEl.textContent = user.displayName ?? user.email ?? "";
  authSection.style.display = "block";
  loginBtn.style.display = "none";
}
Authon — Universal Authentication Platform