此页面暂无简体中文版本,现以英文显示。
OAuth 2.1 + PKCE app sign-in
How the zmle mobile and desktop apps sign in: discovery, authorization code with S256 PKCE, rotating refresh tokens and revocation.
zmle-mobile and zmle-desktop; there is no registration for third-party OAuth clients yet. Your own integrations use API keys. Learn this flow to understand app tokens (fx_at_…) you may see in the API request log, or if you work on the zmle apps.The flow
Discover the endpoints:
GET /.well-known/oauth-authorization-server(RFC 8414) returnsauthorization_endpoint,token_endpoint,revocation_endpointandx-workspace(name, logo, API base).Create a PKCE pair: a random
code_verifier(43–128 chars) andcode_challenge = base64url(SHA-256(verifier)). OnlyS256is accepted.Open
/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&state=…. The person signs in (two-step sign-in and accepted terms apply) and clicks Allow.zmle redirects to
redirect_uri?code=…&state=…. The code is 256-bit, single-use and valid for 2 minutes.Exchange it at
POST /api/oauth/tokenwithgrant_type=authorization_codeand thecode_verifier.Use the access token (
fx_at_…, 1 hour) asAuthorization: Beareron/api/v1. Refresh withgrant_type=refresh_token(fx_rt_…, 60 days).
import { createHash, randomBytes } from "node:crypto";
const WORKSPACE = "https://your-workspace.zmle.com";
const REDIRECT = "http://127.0.0.1:53682/callback"; // loopback: 127.0.0.1 or [::1], port 1024+, path /callback
const verifier = randomBytes(32).toString("base64url"); // 43 characters
const challenge = createHash("sha256").update(verifier).digest("base64url"); // S256
const state = randomBytes(16).toString("base64url");
const authorize = new URL("/oauth/authorize", WORKSPACE);
authorize.search = new URLSearchParams({
response_type: "code",
client_id: "zmle-desktop",
redirect_uri: REDIRECT,
code_challenge: challenge,
code_challenge_method: "S256",
state,
}).toString();
console.log("Open:", authorize.toString());
// After the redirect: check state, then exchange the code.
export async function exchange(code: string) {
const res = await fetch(WORKSPACE + "/api/oauth/token", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ grant_type: "authorization_code", code, client_id: "zmle-desktop", redirect_uri: REDIRECT, code_verifier: verifier }),
});
if (!res.ok) throw new Error((await res.json()).error_description);
return res.json(); // { access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope, user, workspace }
}Rules worth knowing
- Refresh tokens rotate on every use. Using an old (already rotated) refresh token again revokes the whole sign-in.
- An app token acts as the signed-in person: its API scopes are what that person's role permissions allow (
SCOPE_PERMISSIONinsrc/lib/api-v1/oauth-core.ts), re-checked on every request. App tokens never get*. - Staff who still owe two-step enrolment or document acceptance get
403 action_required. POST /api/oauth/revoke(RFC 7009) ends the sign-in; people can also end app sign-ins under Download the apps → My app sign-ins.- Only hashes of codes and tokens are stored.
Written from: docs/APPS.md, docs/API.md, src/lib/api-v1/oauth-core.ts, src/lib/api-v1/oauth.ts, src/app/api/oauth/token/route.ts, src/app/.well-known/oauth-authorization-server/route.ts