接入文档

亦匿统一验证基于 OAuth 2.0 授权码模式（Authorization Code + PKCE），所有端点均为标准 HTTPS 请求，返回 JSON。

本节为当前协议说明。官方接入文档（最终版）发布后，此处内容将按正式文档更新。如需先接入，可按下方协议开发，二者兼容。

一、端点一览

端点	方法	用途
`authorize.php`	GET	引导用户登录并授权，回调携带授权码
`token.php`	POST	用授权码换取令牌 / 刷新令牌
`userinfo.php`	GET	用访问令牌获取用户资料

站点根地址以实际部署为准（如 https://auth.yini.l.cd）。

二、授权码流程

在「开发者中心」注册应用，填写回调地址，获得 client_id 与 client_secret。
跳转授权：authorize.php?response_type=code&client_id=…&redirect_uri=…&scope=profile&state=随机串
用户登录并同意后，回调：redirect_uri?code=…&state=…（校验 state 是否一致）。
服务端 POST 至 token.php 换取令牌（见下）。
携带 Authorization: Bearer <access_token> 请求 userinfo.php 获取用户信息。

三、令牌换发

请求（机密型应用带 client_secret；公开型应用必须使用 PKCE）：

POST token.php
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=你的_client_id
&client_secret=你的_client_secret   // 机密型
&code=上一步拿到的授权码
&redirect_uri=注册时的回调地址
&code_verifier=PKCE验证串           // 公开型/PKCE 必填

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "…",
  "scope": "profile"
}

刷新令牌（轮换模式，旧令牌即刻作废）：

POST token.php
grant_type=refresh_token
&client_id=…
&client_secret=…
&refresh_token=…

四、用户信息

GET userinfo.php
Authorization: Bearer <access_token>

{ "sub": 1, "username": "demo", "scope": "profile", "iat": …, "exp": … }

scope 含 email 时，响应附带 email 字段。sub 即用户唯一 ID。

五、PKCE（推荐）

前端应用（无密钥可藏）务必使用：授权跳转时带上 code_challenge 与 code_challenge_method=S256，换码时提交 code_verifier。

code_verifier  = 43-128 位随机串
code_challenge = base64url(sha256(code_verifier))

六、错误响应

error	含义
`invalid_request`	请求参数缺失或非法
`invalid_client`	客户端不存在/停用/密钥错误
`invalid_grant`	授权码/刷新令牌无效、过期或已被使用
`invalid_token`	访问令牌无效或过期
`unsupported_grant_type`	不支持的 grant_type
`access_denied`	用户拒绝了授权

七、示例：PHP 服务端接入

// 1. 生成授权地址（请自行实现 code_verifier 存储）
$auth = 'https://你的站点/authorize.php?response_type=code'
      . '&client_id=你的_client_id'
      . '&redirect_uri=' . urlencode('https://你的应用/oauth/callback.php')
      . '&scope=profile&state=' . $state;
header('Location: ' . $auth);

// 2. 回调后换码
$r = http_post('https://你的站点/token.php', array(
    'grant_type' => 'authorization_code',
    'client_id' => $client_id, 'client_secret' => $secret,
    'code' => $_GET['code'], 'redirect_uri' => $callback,
));
$json = json_decode($r, true);

// 3. 取用户信息
$u = file_get_contents('https://你的站点/userinfo.php', false,
    stream_context_create(array('http' => array(
        'header' => 'Authorization: Bearer ' . $json['access_token'])))

官方接入文档（包含各产品站的具体对接参数、注意事项与常见问题）补充后将在此页发布。