登录端点(authorize / token / me)
三个登录端点的参数和返回。
平台公开 OpenAPI 规格后,这一页会换成按端点一页的参考。流程和能跑的代码见教程登录。
authorize
GET {issuer}/api/v1/apps/authorize(公开端点,query 原样转给授权页;query 超过 4 KiB 回 400)
| 参数 | 要求 | 说明 |
|---|---|---|
response_type |
必填 | 固定 code |
client_id |
必填 | App ID(app_…) |
redirect_uri |
必填 | 必须和安装版本 manifest 里登记的 redirect_uri 逐字节相同 |
state |
必填 | 1–512 个可见 ASCII 字符,原样带回,平台不存。用不可猜的随机值,不要把返回路径等数据塞进去 |
code_challenge |
必填 | BASE64URL(SHA256(code_verifier)),43 个字符 |
code_challenge_method |
必填 | 只能是 S256(plain 拒绝) |
nonce |
要带 | 平台侧可选(≤256 个可见 ASCII),原样写进 id_token 的 nonce。请带上,并在回调里核对,防 id_token 重放 |
scope |
可选 | 空格分隔,只能缩小安装时已批准的 scope(超出报 invalid_scope);不传 = 全部已批准 scope;openid 接受但忽略 |
prompt |
可选 | 接受但没有效果:授权从不需要成员交互 |
其他未知参数(login_hint、ui_locales、claims 等)一律忽略,不报错。
回调(GET {redirect_uri}?…):成功时带 code、state、iss;失败时带 error、error_description、iss,请求里的 state 合法时还带回 state(不合法时,报的就是它)。失败时也带 iss,先核它再看 error(RFC 9207)。每一步怎么处理见登录。
token
POST {issuer}/api/v1/apps/token:application/x-www-form-urlencoded(也接受 JSON)。客户端认证只认 App ID + App Secret:body 里的 client_id / client_secret(或别名 app_id / app_secret),或 HTTP Basic。错误按 RFC 6749 §5.2 返回。
{
"access_token": "eyJ…", // JWT(typ at+jwt),sub = member_id,15 分钟
"token_type": "Bearer",
"expires_in": 900,
"id_token": "eyJ…", // typ JWT,RS256
"scope": "org:me:read org:me.email:read",
"refresh_token": "cwrt_…", // 仅当授权含 offline_access
"user": { "member_id": "…", "org_id": "…", "name": "…", "org_role": "member", "email": "…" }
}
- id_token 的 claims:
iss、aud(App ID)、sub=member_id、member_id、org_id、name、org_role、email(仅在有org:me.email:read时)、nonce、iat、exp。 org_role只供参考,不是平台授权;入口里的权限由你按绑定的账号自己判断。access_token只当Authorization: Bearer调/api/v1/*;id_token 不能当 Bearer 用。- 刷新(需要
offline_access):grant_type=refresh_token,有效期 30 天。每次刷新都会轮换,必须保存新的 refresh_token;旧的被重放会吊销整条链(轮换后 30 秒内的并发 / 重试除外)。每次刷新都会重新检查安装和成员状态,scope 只能缩小。 - 撤销:
POST {issuer}/api/v1/apps/token/revoke(RFC 7009,只收 refresh_token,连同整条链一起撤销)。access_token 不单独撤销,15 分钟内自然过期;安装停用、卸载或收窄 scope 时立即失效(其他副本最多 30 秒)。 - JWKS 公开,
Cache-Control: max-age=300。遇到不认识的kid就重新拉一次(要限频);轮换期间旧 key 仍会列出。
me
GET {issuer}/api/v1/me,Authorization: Bearer <access_token>,需要 org:me:read。
- 200:token 有效,这个人仍是本组织成员,安装仍可用。字段包在
data里:data.member_id、data.org_id、data.org_name、data.display_name、data.role.slug(org-owner/org-admin/org-member)等,外层另有request_id和server_time(见下面的样例)。 - 401:token 失效(过期、安装停用 / 卸载 / 收窄、成员离开)→ 重新授权。
- 403:没批
org:me:read→ 修 manifest 的 scope。
{
"data": { "member_id": "…", "org_id": "…", "org_name": "…", "display_name": "…", "role": { "slug": "org-member" } },
"request_id": "…",
"server_time": "…"
}
只需要在登录时确认身份的应用,验完 id_token 后可以直接丢掉 access_token。注意:/api/v1/me 返回 200 只说明「此刻仍有效」,不会延长任何东西(见下一节)。
