Developer Docs

Integrate ZDX Auth without sharing platform cookies

External apps send user credentials to ZDX Auth, receive a one-time callback code, exchange it for tokens, and create their own local sessions. ZeroDriveX remains the identity and token authority.

Register a client app

Create a tenant client, store its generated secret safely, then configure exact redirect URIs and allowed origins.

Start password login

POST user email, password, redirect_uri, optional origin, optional scope, and optional state to /api/auth/apps/[clientId]/login.

Exchange code

POST the one-time authorization code to /api/oauth/token with the exact redirect_uri and client credentials.

Verify token

Call /api/auth/tokens/verify from your server using AUTH_GATEWAY_SECRET. Never verify privileged access in the browser.

Core flow

POST /api/auth/apps/[clientId]/login
GET  /client/auth/callback?code=...
POST /api/oauth/token
POST /api/auth/tokens/verify
POST /api/auth/tokens/refresh
POST /api/auth/tokens/revoke

{
  "email": "user@example.com",
  "password": "user-password",
  "redirect_uri": "https://your-app.com/auth/callback",
  "origin": "https://your-app.com",
  "scope": "openid profile email",
  "state": "csrf-or-return-state"
}

Security defaults

Validate redirect URIs exactly.
Validate allowed origins for browser-started login.
Require tenant membership and a role allowed by the client app.
Store refresh tokens and client secrets only as hashes.
Verify signature, issuer, audience, exp, jti, DB validity, and revocation state.

Onboarding assistant

Authenticated users can open `/user/onboarding` or `/admin/onboarding` to ask the server-side Ollama assistant about app password login, callback exchange, local sessions, token verification, refresh, revoke, redirect URIs, origins, roles, and tenant setup. The assistant receives redacted setup status and cannot change billing, plans, limits, or access.

Next step

Use the developer guide for a step-by-step production launch path.

Open Developer Guide