सीधे कंटेंट पर जाएँ
14 दिन का मुफ़्त ट्रायल, कार्ड नहीं चाहिए9 भाषाएँ176 व्यवसाय प्रकार · 50 ऐप
HI· USD
लाइव डेमो आज़माएँमुफ़्त ट्रायल शुरू करें

यह पेज अभी हिन्दी में उपलब्ध नहीं है, इसलिए इसे अंग्रेज़ी में दिखाया जा रहा है।

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.

  • about 10 min
Today the OAuth server knows only the first-party public clients 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

  1. Discover the endpoints: GET /.well-known/oauth-authorization-server (RFC 8414) returns authorization_endpoint, token_endpoint, revocation_endpoint and x-workspace (name, logo, API base).

  2. Create a PKCE pair: a random code_verifier (43–128 chars) and code_challenge = base64url(SHA-256(verifier)). Only S256 is accepted.

  3. 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.

  4. zmle redirects to redirect_uri?code=…&state=…. The code is 256-bit, single-use and valid for 2 minutes.

  5. Exchange it at POST /api/oauth/token with grant_type=authorization_code and the code_verifier.

  6. Use the access token (fx_at_…, 1 hour) as Authorization: Bearer on /api/v1. Refresh with grant_type=refresh_token (fx_rt_…, 60 days).

PKCE + authorize URL (desktop loopback client)
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_PERMISSION in src/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