API documentation

Integration reference for downstream systems connecting to Ecox SSO. Public — no account required.

OIDC-shaped, not full OIDC/OAuth2. Ecox SSO is authentication only — it proves who a user is; it does not implement the OAuth2 authorization-code flow (/authorize, /token, PKCE, refresh tokens, scopes). Import openapi.yaml into your own tool (Swagger UI, Postman, a codegen client) for the full machine-readable contract.

Discovery & keys

Call these — cacheable, machine-to-machine. Bootstrap your integration from the discovery document rather than hardcoding the issuer or key material.

Method	Path	Purpose
GET	`/.well-known/openid-configuration`	Issuer + `jwks_uri` + supported alg/claims.
GET	`/.well-known/jwks.json`	Current public signing key(s) — both retiring and new key are published during a rotation overlap.

curl https://sso.wewillapp.com/.well-known/openid-configuration

curl https://sso.wewillapp.com/.well-known/jwks.json

Login flow — a browser redirect, not an API call

Send the user's browser here with a 302; these are not endpoints your app code calls directly.

Method	Path	Purpose
GET	`/login?redirect=...`	Renders the login form, or silently re-mints a token if the browser already has a valid session (single sign-on).
GET	`/renew?redirect=...`	Silently tops up the token before its short (≤ 15 minutes) expiry.
GET/POST	`/logout`	Confirm + revoke the session, clear cookies.

redirect is honoured ONLY for an absolute https:// URL whose host is wewillapp.com or a *.wewillapp.com subdomain, with no userinfo. Anything else (off-domain host, http:, protocol-relative //host) falls back to a safe default landing — a rejected value never errors.

Validating the token

Read the __Secure-sso_token cookie. Verify: RS256 signature (key selected by the JWT header kid from your cached JWKS), exp, iss (https://sso.wewillapp.com), and that aud contains wewillapp-internal. Fail closed on any error (invalid/expired/unknown-kid/JWKS-unreachable) — treat as unauthenticated and 302 the browser to /login?redirect=<your app URL>.

Claim	Meaning
`iss`	https://sso.wewillapp.com — stable forever; MUST verify.
`sub`	Stable user id (uuid) — key your role mapping off this.
`aud`	wewillapp-internal (fixed audience). SHOULD verify.
`exp` / `iat` / `nbf`	Standard JWT timestamps — max lifetime 15 minutes.
`jti`	Unique token id (audit correlation).
`sid`	Server-session id (correlation).
`preferred_username` / `name` / `email`	Always present.

There is NO role / admin / permission claim — by design. Ecox SSO authenticates; each app authorizes from sub. Do not expect any authorization data in the token.

Cookies

__Secure-sso_token — the RS256 JWT downstream apps verify. Read this one.
__Host-sso_session — opaque server-session id, SSO-internal. Apps ignore it.
__Host-sso_csrf — signed double-submit CSRF cookie for the pre-auth login form. Not relevant to a downstream app.

Health & liveness

Method	Path	Purpose
GET	`/health`	Deep check (DB, migrations, signing-key canary). Returns 200 only if every check passes, otherwise 503.
GET	`/livez`	Bare liveness — no dependency checks.

Source of truth is live, not this page — always bootstrap from the discovery endpoints above rather than hardcoding key material. Full machine-readable contract: /docs/openapi.yaml.