OpenMax
免费试用

登录端点(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 只说明「此刻仍有效」,不会延长任何东西(见下一节)。