接入文档

OAuth 2.0 授权码模式的起点。用户在此页面登录并确认授权后，服务端将授权码通过 redirect_uri 返回给客户端。公共客户端（移动应用 / SPA）必须携带 code_challenge，否则返回 invalid_request。

请求参数

请求示例

GET https://auth.401522.xyz/v2/authorize.php
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-site.com%2Fcallback
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

响应示例

HTTP/1.1 302 Found
Location: https://your-site.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

响应字段

错误响应

颁发令牌对。支持两种 grant_type：authorization_code（用授权码换令牌）与 refresh_token（用刷新令牌换新令牌对）。refresh_token 为严格一次性凭据，刷新后旧令牌立即失效。

请求参数

请求示例

POST https://auth.401522.xyz/v2/token.php
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://your-site.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_CODE_VERIFIER

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "access_token": "a1b2c3d4e5f6…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "r1e2f3a4b5c6…",
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJIUzI1NiIs…"
}

响应字段

错误响应

OIDC 标准 UserInfo 端点。根据访问令牌返回用户身份信息，返回字段受 scope 控制。用户被封禁时返回 user_banned。

请求参数

请求示例

GET https://auth.401522.xyz/v2/userinfo.php
Authorization: Bearer ACCESS_TOKEN

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "sub": "1",
  "name": "username",
  "preferred_username": "username",
  "email": "user@example.com",
  "email_verified": true,
  "role": "user",
  "created_at": "2025-01-01 10:00:00"
}

响应字段

错误响应

供服务端后台使用的应用级接口。与 UserInfo 不同，本接口必须同时携带 API KEY 与访问令牌，且令牌必须属于同一个 client_id，返回字段固定完整（不受 scope 控制）。

请求参数

请求示例

GET https://auth.401522.xyz/v2/user.php?client_id=YOUR_CLIENT_ID&api_key=YOUR_API_KEY
Authorization: Bearer ACCESS_TOKEN

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "id": 1,
  "sub": "1",
  "username": "username",
  "name": "username",
  "email": "user@example.com",
  "email_verified": true,
  "role": "user",
  "created_at": "2025-01-01 10:00:00"
}

响应字段

错误响应

使用 refresh_token 换取新的令牌对。严格一次性轮换：刷新成功后旧 refresh_token 与旧 access_token 立即失效，若重复使用将返回 refresh_token_used。

请求参数

请求示例

POST https://auth.401522.xyz/v2/refresh.php
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "access_token": "n1e2w3t4k5j6…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "n1r2e3f4r5e6…",
  "scope": "openid profile email"
}

响应字段

错误响应

撤销访问令牌或刷新令牌（RFC 7009）。符合规范：无论令牌是否存在、是否已被撤销，均返回 200，通过响应字段区分结果。

请求参数

请求示例

POST https://auth.401522.xyz/v2/revoke.php
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "revoked": true,
  "changed": true,
  "status": "revoked"
}

响应字段

错误响应

查询令牌当前状态（RFC 7662）。同时支持访问令牌与刷新令牌；令牌不存在时返回 active: false 而非报错。

请求参数

请求示例

POST https://auth.401522.xyz/v2/introspect.php
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_INTROSPECT
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "active": true,
  "scope": "openid profile email",
  "client_id": "fusion_xxx",
  "username": "username",
  "token_type": "Bearer",
  "exp": 1735660800,
  "iat": 1735574400,
  "sub": "1",
  "status": "active"
}

响应字段

错误响应

查询 API KEY 状态、轮换（生成新 KEY，旧 KEY 立即失效）或作废（不生成新 KEY）。轮换时可选设置新 KEY 的有效期（天）。

请求参数

请求示例

# 查询状态
GET https://auth.401522.xyz/v2/keys.php?client_id=YOUR_CLIENT_ID&api_key=YOUR_API_KEY

# 轮换（30 天后过期）
POST https://auth.401522.xyz/v2/keys.php?client_id=YOUR_CLIENT_ID&api_key=YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

action=rotate&ttl_days=30

# 仅作废
POST https://auth.401522.xyz/v2/keys.php?client_id=YOUR_CLIENT_ID&api_key=YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

action=revoke

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "rotated": true,
  "api_key": "sk_NEW_KEY_ONLY_SHOWN_ONCE",
  "api_key_masked": "sk_9f2c…7b41",
  "previous_key_revoked_at": 1730000000,
  "expires_at": 1732592000,
  "expires_in": 2592000,
  "notice": "新 API KEY 仅在本次响应中返回，请立即保存。旧 API KEY 已立即失效。"
}

响应字段

错误响应

支撑「网页 → intent → 安卓客户端 → 验证 → 回传网页」链路。共 4 个 action：ticket 申请一次性票据、verify 客户端提交令牌、status 网页轮询结果、check 网页服务端校验断言。

请求参数

请求示例

# ① 网页申请一次性票据
POST https://auth.401522.xyz/v2/verify.php
Content-Type: application/x-www-form-urlencoded

action=ticket&client_id=YOUR_CLIENT_ID
&redirect_uri=https://your-site.com/verify-callback
&state=RANDOM_STATE&nonce=RANDOM_NONCE

# ② 唤起安卓客户端（网页侧发起）
intent://oauth/verify?S.ticket=TICKET#Intent;
  scheme=fusionoauth;package=xyz.uoxvx.fusionoauth;end

# ③ 客户端提交令牌完成验证
POST https://auth.401522.xyz/v2/verify.php
Content-Type: application/x-www-form-urlencoded

action=verify&client_id=YOUR_CLIENT_ID
&ticket=TICKET&access_token=ACCESS_TOKEN

# ④ 网页服务端校验断言
POST https://auth.401522.xyz/v2/verify.php
Content-Type: application/x-www-form-urlencoded

action=check&client_id=YOUR_CLIENT_ID
&assertion=ASSERTION_FROM_STATUS

响应示例

{
  "api_version": "v2",
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "ticket": "9f3c…7b41",
  "expires_in": 300,
  "intent_url": "intent://oauth/verify?S.ticket=9f3c…#Intent;scheme=fusionoauth;package=xyz.uoxvx.fusionoauth;end",
  "app_links_url": "https://your-host/android/verify.php?ticket=9f3c…"
}

响应字段

错误响应

获取无状态图形验证码。返回签名令牌与图片，登录时需一并回传。令牌一次性使用，5 分钟过期。

请求示例

GET https://auth.401522.xyz/api/mobile/captcha.php

响应示例

{
  "api_version": "mobile",
  "captcha_token": "eyJjIjoi…",
  "image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0…",
  "svg": "<svg xmlns=…</svg>",
  "expires_in": 300
}

响应字段

错误响应

使用用户名或邮箱 + 密码换取移动端令牌对。成功后令牌可用于调用全部移动端接口。

请求参数

请求示例

POST https://auth.401522.xyz/api/mobile/login.php
Content-Type: application/json

{
  "account": "yourname",
  "password": "your-password",
  "captcha_token": "eyJjIjoi…",
  "captcha": "A7K2",
  "device": "android/34 Pixel 8"
}

响应示例

{
  "api_version": "mobile",
  "access_token": "mat_9f3c7b41…",
  "refresh_token": "mrt_2e8d4a10…",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": 1793548800,
  "user": {
    "id": 12,
    "username": "yourname",
    "email": "you@example.com",
    "email_verified": true,
    "role": "user",
    "created_at": "2026-01-02 10:30:00",
    "is_admin": false
  }
}

响应字段

错误响应

使用刷新令牌换取新的访问令牌。旧访问令牌立即失效。

请求参数

请求示例

POST https://auth.401522.xyz/api/mobile/refresh.php
Content-Type: application/json

{
  "refresh_token": "mrt_2e8d4a10…"
}

响应示例

{
  "api_version": "mobile",
  "access_token": "mat_c8a0f180…",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": 1793548800
}

响应字段

错误响应

一次获取账号信息、统计数字、系统公告与最近应用，供客户端控制台首页渲染。

请求示例

GET https://auth.401522.xyz/api/mobile/dashboard.php
Authorization: Bearer mat_9f3c7b41…

响应示例

{
  "api_version": "mobile",
  "user": {
    "id": 12, "username": "yourname", "email": "you@example.com",
    "email_verified": true, "role": "user",
    "created_at": "2026-01-02 10:30:00", "is_admin": false
  },
  "stats": {
    "app_count": 3, "authorization_count": 12,
    "active_count": 9, "revoked_count": 3
  },
  "apps": [ { "id": 1, "name": "我的应用", "client_id": "fusion_…", "status_label": "正常" } ],
  "announcements": [
    { "title": "系统维护通知", "content": "本周六 02:00-04:00 进行维护。", "created_at": "2026-10-20 09:00:00" }
  ]
}

响应字段

错误响应

列出、新建、修改、轮换密钥、作废密钥与删除自己的应用。列表只返回掩码后的 API KEY。

请求参数

请求示例

POST https://auth.401522.xyz/api/mobile/apps.php
Authorization: Bearer mat_9f3c7b41…
Content-Type: application/json

{
  "action": "create",
  "name": "我的移动应用",
  "client_type": "app",
  "redirect_uris": "fusionoauth://oauth/callback",
  "app_package": "com.example.myapp"
}

响应示例

{
  "api_version": "mobile",
  "app": {
    "id": 5,
    "client_id": "fusion_Ll64HxtbD6yk2w352v4sw",
    "name": "我的移动应用",
    "client_type": "app",
    "client_type_label": "移动应用",
    "redirect_uris": ["fusionoauth://oauth/callback"],
    "app_package": "com.example.myapp",
    "api_key_masked": "sk_42933…f06b",
    "has_api_key": true,
    "status": "pending",
    "status_label": "待审核",
    "created_at": "2026-11-01 09:30:00"
  },
  "client_secret": "…",
  "api_key": "sk_429338a3a…",
  "notice": "应用创建成功，等待管理员审核通过后方可调用 API。…"
}

响应字段

错误响应

列出自己的授权记录，撤销单条授权或撤销某应用的全部授权。

请求参数

请求示例

POST https://auth.401522.xyz/api/mobile/authorizations.php
Authorization: Bearer mat_9f3c7b41…
Content-Type: application/json

{
  "action": "revoke",
  "id": 128
}

响应示例

{
  "api_version": "mobile",
  "authorizations": [
    {
      "id": 128,
      "client_id": "fusion_Ll64HxtbD6yk2w352v4sw",
      "app_name": "我的移动应用",
      "scope": "openid profile email",
      "created_at": "2026-10-28 14:20:00",
      "expires_at": "2026-11-27 14:20:00",
      "revoked": false,
      "expired": false,
      "active": true
    }
  ],
  "total": 12,
  "active_count": 9,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

响应字段

错误响应

注销当前移动端令牌，使其立即失效。

请求示例

POST https://auth.401522.xyz/api/mobile/logout.php
Authorization: Bearer mat_9f3c7b41…

响应示例

{
  "api_version": "mobile",
  "revoked": true
}

响应字段

错误响应