API 参考

API 参考

Authon 认证服务的完整 REST API 文档。所有请求必须在 x-api-key 头部包含 API 密钥，或在 Authorization.

基础 URL

text
https://api.authon.dev

认证

Authon 根据请求来源（浏览器或服务器）使用两种类型的 API 密钥。在 x-api-key 头部或作为 Bearer 令牌传递密钥。

密钥类型前缀用途
可公开密钥pk_live_ / pk_test_浏览器 / 客户端 SDK。可安全暴露。
私密密钥sk_live_ / sk_test_仅服务器端。完整管理员权限。切勿暴露。
BearereyJhbGci...登录获取的用户访问令牌。有效期15分钟。
bash
# Publishable key — client-side requests
curl https://api.authon.dev/v1/auth/providers \
  -H "x-api-key: pk_live_your_publishable_key"

# Secret key — server-side admin requests
curl https://api.authon.dev/v1/auth/token/verify \
  -H "x-api-key: sk_live_your_secret_key" \
  -H "Authorization: Bearer eyJhbGci..."

# Bearer access token — user requests
curl https://api.authon.dev/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

认证端点

POST/v1/auth/signup

注册

使用邮箱和密码注册新用户。成功时返回令牌。

Auth:x-api-key: pk_live_...
请求体
json
{
  "email": "user@example.com",
  "password": "securepassword",
  "displayName": "Jane Doe"          // optional
}
响应
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": {
    "id": "usr_abc123",
    "projectId": "proj_xyz",
    "email": "user@example.com",
    "displayName": "Jane Doe",
    "avatarUrl": null,
    "emailVerified": false,
    "isBanned": false,
    "publicMetadata": null,
    "signInCount": 0,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}
POST/v1/auth/signin

登录

使用邮箱和密码认证现有用户。

Auth:x-api-key: pk_live_...
请求体
json
{
  "email": "user@example.com",
  "password": "securepassword"
}
响应
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": { ... }
}
POST/v1/auth/signout

退出登录

撤销当前会话并使刷新令牌失效。需要 Bearer 访问令牌。

Auth:Authorization: Bearer <access_token>
响应
json
{
  "success": true
}
POST/v1/auth/token/refresh

刷新令牌

使用刷新令牌换取新的访问令牌。访问令牌在15分钟后过期。

Auth:x-api-key: pk_live_...
请求体
json
{
  "refreshToken": "rt_8f4a2b1c..."
}
响应
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}
GET/v1/auth/token/verify

验证令牌

验证访问令牌并返回关联的用户。由您的服务器用于认证传入请求。

Auth:x-api-key: sk_live_...
响应
json
{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "emailVerified": true,
  "isBanned": false,
  "publicMetadata": { "plan": "pro" },
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
GET/v1/auth/me

获取当前用户

返回当前已认证用户的资料。

Auth:Authorization: Bearer <access_token>
响应
json
{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "avatarUrl": "https:0
  6: null,
  7: true,
  8: false,
  9: false,
  10: {},
  11: "2026-01-15T10:30:00.000Z",
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
PATCH/v1/auth/me

更新当前用户

更新当前已认证用户的资料字段。仅更新提供的字段。

Auth:Authorization: Bearer <access_token>
请求体
json
{
  "displayName": "Jane Smith",          // optional
  "avatarUrl": "https://example.com/avatar.png"  // optional
}
响应
json
{
  "id": "usr_abc123",
  "displayName": "Jane Smith",
  "avatarUrl": "https://example.com/avatar.png",
  ...
}

OAuth 端点

GET/v1/auth/providers

列出登录方式

返回项目中已启用的 OAuth 登录方式列表。

Auth:x-api-key: pk_live_...
响应
json
{
  "providers": ["google", "github", "kakao"]
}
GET/v1/auth/oauth/:provider/url

获取 OAuth URL

为指定 OAuth 登录方式生成授权 URL。用于重定向用户或打开弹窗。

Auth:x-api-key: pk_live_...
响应
json
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}
POST/v1/auth/oauth/callback

OAuth 回调

将 OAuth 授权码换取 Authon 令牌。弹窗返回后由 SDK 调用。

Auth:x-api-key: pk_live_...
请求体
json
{
  "provider": "google",
  "code": "4/0AX4XfWh...",
  "state": "random_state_string",
  "codeVerifier": "pkce_verifier"   // required if PKCE was used
}
响应
json
{
  "accessToken": "eyJhbGci...",
  "refreshToken": "rt_...",
  "expiresIn": 900,
  "user": { ... }
}

品牌设置

GET/v1/auth/branding

获取品牌设置

返回项目的品牌配置。JS SDK 用此数据为登录弹窗设置样式。

Auth:x-api-key: pk_live_...
响应
json
{
  "brandName": "Acme Corp",
  "primaryColorStart": "#7c3aed",
  "primaryColorEnd": "#4f46e5",
  "lightBg": "#ffffff",
  "lightText": "#111827",
  "darkBg": "#0f172a",
  "darkText": "#f1f5f9",
  "borderRadius": 12,
  "showEmailPassword": true,
  "showDivider": true,
  "termsUrl": "https:0
  13: "https://acme.com/privacy",
  "logoDataUrl": "data:image/png;base64,..."
}

错误代码

所有错误响应遵循统一格式，包含 HTTP 状态码和 JSON 响应体：

json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}
状态码错误描述
400Bad Request请求体缺失或格式错误
401UnauthorizedAPI 密钥 / 令牌缺失、无效或已过期
403Forbidden密钥有效但无此操作权限
404Not Found请求的资源不存在
409Conflict邮箱已被注册
422Unprocessable Entity验证失败 — 请检查字段要求
429Too Many Requests超出速率限制 — 请在指定延迟后重试
500Internal Server Error意外的服务器端错误
Authon — Universal Authentication Platform