UniAuth
RESTful + OIDC

API 参考文档

UniAuth REST API 的完整参考文档。符合标准的 OAuth 2.0、OpenID Connect、SCIM 2.0 与管理端点，每条路由都具备一致的错误处理与速率限制。

快速入门

三个步骤即可上手

从取得 API 密钥到发出第一个已验证的请求，只需不到五分钟。

1
取得你的 API 密钥

创建帐户并在开发者主控台中注册一个 OAuth 用户端。你会取得一组 client_id 与 client_secret。

# Developer console
https://uniauth.id/account/developer

# Or via Admin API
POST /api/admin/oauth-clients
{
  "name": "My App",
  "redirect_uris": ["https://app.example/cb"]
}
2
发出你的第一个请求

使用权杖端点，将授权码换取访问权杖与 ID 权杖。

curl -X POST https://uniauth.id/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_SECRET" \
  -d "redirect_uri=https://app.example/cb" \
  -d "code_verifier=PKCE_VERIFIER"
3
处理回应

权杖端点会回传访问权杖、ID 权杖与刷新权杖。使用访问权杖即可调用受保护的端点。

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh...",
  "id_token": "eyJhbGci...",
  "scope": "openid profile email"
}
端点

依类别划分的 API 端点

32 个端点，分为六大群组。每个端点都会强制运行速率限制、验证 Content-Type，并回传一致的错误对象。

验证

6 个端点
POST
/api/auth/login

以电子邮件与密码验证用户。回传工作阶段权杖，并在已激活时触发 2FA。

POST
/api/auth/register

以电子邮件、密码及选填的个人数据字段创建新的用户帐户。

POST
/api/auth/logout

终止目前的工作阶段、撤销权杖，并为 OAuth 用户端触发后信道/前信道注销。

POST
/api/auth/forgot-password

寄送一封含有 SHA-256 哈希、有时效性权杖的密码重设电子邮件。

POST
/api/auth/reset-password

使用 forgot-password 取得的权杖重设密码。会强制运行密码历史与强度检查。

POST
/api/auth/verify-email

使用注册时寄送的验证权杖确认电子邮件的所有权。

OAuth 2.0 / OIDC

6 个端点
GET
/api/oauth/authorize

启动采用 PKCE 的 OAuth 2.0 授权码流程。先重新导向至登录，再导向至授权同意画面。

POST
/api/oauth/token

将授权码换取权杖、刷新权杖，或处理 device/client-credentials 授权类型。

GET
/api/oauth/userinfo

回传已验证用户的 OIDC 声明。依 OIDC Core 第 5.3.1 节支持 GET 与 POST。

POST
/api/oauth/revoke

撤销访问权杖或刷新权杖。支持 token_type_hint 参数。

POST
/api/oauth/introspect

查看权杖以判断其有效状态、范围与中继数据（RFC 7662）。

GET
/.well-known/openid-configuration

OIDC 探索文档，包含所有端点、支持的范围、声明与算法。

用户管理

4 个端点
GET
/api/user/profile

截取已验证用户的完整个人数据，包含 OIDC 标准声明与偏好设置。

PUT
/api/user/profile

更新个人数据字段：显示名称、简介、地区设置、社群链接、地址等。

GET
/api/user/sessions

列出已验证用户的所有作用中工作阶段，并附上设备信息与最近活动。

DELETE
/api/user/sessions

依 ID 撤销特定工作阶段，或撤销所有其他工作阶段（密码变更时的失效机制）。

组织／团队

8 个端点
POST
/api/user/organizations

自助创建组织。创建者将成为拥有者（最多可拥有 10 个组织）；以 team 方案开始。

GET
/api/org/{id}/users

列出并管理组织成员与角色（owner/admin/member）。team 方案上限为 25 个席位（超过时回传 HTTP 402）。

POST
/api/org/{id}/invitations

以电子邮件邀请成员，并通过权杖接受。容量会在邀请与接受时皆强制检查。

POST
/api/org/{id}/groups

创建并管理组织群组与成员。群组名称会出现在 OIDC 的 groups 声明中。

POST
/api/org/{id}/clients/{cid}/scim-token

为组织签发或轮替各用户端的 SCIM 权杖。enterprise 方案——否则回传 402 upgrade_required。

POST
/api/org/{id}/domains

为组织新增并验证自定义网域。enterprise 方案——用于控管网域范围的 SSO 与采集。

POST
/api/org/{id}/saml-idps

设置传入 SSO：SAML SP 与 OIDC 联合 IdP（亦含 /federated-idps）。enterprise 方案。

GET
/api/org/{id}/billing

各组织的 Stripe 计费：订阅状态、席位与结账。每个组织都是独立的客户，依席位计费。

SCIM 2.0 布建

4 个端点
GET
/api/scim/v2/Users

以 SCIM 筛选语法列出或搜索用户。支持分页与属性投影。

POST
/api/scim/v2/Users

通过 SCIM 布建新用户。将 SCIM 用户资源结构描述对应至 UniAuth 的 users 数据表。

GET
/api/scim/v2/Groups

列出或搜索群组。包含成员参照，并支持筛选查找。

POST
/api/scim/v2/Bulk

在单一请求中运行多项 SCIM 操作。每批量最多 100 项操作。

管理

4 个端点
GET
/api/admin/users

列出所有用户，支持分页、搜索、角色筛选与排序。需具备管理员或审核员角色。

GET
/api/admin/analytics

截取平台分析数据：DAU/WAU/MAU、登录趋势、2FA 采用率、验证方法分布。

GET
/api/admin/audit-events

查找防窜改的稽核纪录。可依类别、运行者、目标、日期范围与事件类型筛选。

POST
/api/admin/webhooks

注册一个 Webhook 端点，包含事件订阅与 HMAC-SHA256 签章密钥。

验证

API 验证方法

依端点与使用情境，提供四种验证 API 请求的方式。

Bearer 权杖

在 Authorization 标头中传入访问权杖。用于受 OAuth 保护的端点，例如 userinfo、权杖内省，以及用户端对用户端的 API 调用。

GET /api/oauth/userinfo
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json
Cookie 工作阶段

第一方请求会使用登录后设置的 HttpOnly、Secure、SameSite=Lax Cookie。用于面向用户的页面，以及帐户/管理 API。

GET /api/user/profile
Cookie: auth_token=eyJhbGci...
# HttpOnly — not accessible via JS
# SameSite=Lax — CSRF protection
DPoP（所有权证明）

DPoP（RFC 9449）会将权杖绑定至特定的用户端密钥。请在访问权杖之外一并发送 DPoP 证明 JWT。可防止权杖遭窃与重送。

GET /api/oauth/userinfo
Authorization: DPoP eyJhbGci...
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIs...
# Proof JWT includes htm, htu, iat, jti
SCIM Bearer 权杖

SCIM 布建端点通过每个 OAuth 用户端专属的 SCIM 权杖进行验证。该权杖以 SHA-256 哈希形式保存，并限定於单一组织范围。

GET /api/scim/v2/Users
Authorization: Bearer scim_token_abc123...
Content-Type: application/scim+json
SDK

官方用户端程序库

适用于 JavaScript 与 React 的类型化 SDK，内置 PKCE、权杖生命周期与注销功能。

JavaScript / TypeScript SDK

@uniauth/js

原生 JS 用户端，内置 PKCE、OIDC 探索、权杖自动更新、类型化错误，以及含撤销的注销。可在 Node.js 与浏览器中运作。

npm install @uniauth/js
SDK 参考文档 CDN / 下载

React SDK

@uniauth/react

React 的 provider、hooks 与预先建置的组件：UniAuthProvider、useUser、LoginButton、LogoutButton、ProtectedRoute 与 UserProfile。

npm install @uniauth/react
或通过 CDN： uniauth.id/sdk/uniauth-react.mjs
SDK 参考文档
速率限制

各端点的速率限制

为保护平台，所有端点皆设有速率限制。限制以 15 分钟的滑动窗口重设。

滑动窗口（15 分钟）
POST /api/auth/login
10 个请求
15 分钟
依 IP 计算。失败 5 次后锁定。
POST /api/auth/register
5 个请求
15 分钟
依 IP 计算。防止大量注册。
POST /api/auth/forgot-password
5 个请求
15 分钟
依 IP 计算。不会泄漏帐户是否存在。
POST /api/auth/verify-*
10 个请求
15 分钟
依 IP 计算。涵盖 2FA 与电子邮件。
POST /api/scim/v2/Bulk
10 个请求
15 分钟
依 SCIM 权杖计算。每批量最多 100 项操作。
所有其他端点
100 个请求
15 分钟
依 IP 或权杖计算。双层强制运行。

速率限制标头（X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After）会包含在每个回应中。 设置 Redis 后，限制会在所有服务器运行个体间强制运行。

立即开始集成

从第一天起即享完整 API 访问权。无需信用卡。阅读文档或创建免费帐户即可开始。