Identity overview

Caution

This section is still partly a stub — the unticked items below are a TODO list, not a reference.

The Nyuchi identity layer is built on WorkOS, fronted by the hosted AuthKit domain accounts.mukoko.com. Every Nyuchi product, every Mzizi mini-app, and every mzizi-tools API call ultimately authenticates against the same JWT shape.

The four hosts, and why they are not interchangeable

Three *.mukoko.com subdomains plus one nyuchi.com do four different jobs. Mixing them up fails a long way from the cause, so check this table before setting any host in config:

Host	What it is
accounts.mukoko.com	The WorkOS AuthKit issuer — the OAuth 2.1 authorization server agents and browsers discover. Serves its own self-consistent /.well-known/openid-configuration, /oauth2/authorize, /oauth2/token, /oauth2/jwks and DCR. This is what a WORKOS_ISSUER / WORKOS_AUTHKIT_DOMAIN variable means.
auth.mukoko.com	The WorkOS auth API — what an SDK calls and where an SDK’s JWKS fetch goes. Not an issuer: it serves no authorization-server metadata.
api.nyuchi.com	The Nyuchi API gateway (FastAPI on Fly). Nothing to do with WorkOS.
api.mukoko.com	A separate Mukoko gateway still being built — serves nothing usable yet, and does not resolve today. Also not WorkOS.

Danger

Point an issuer variable at the auth API and you get metadata that validates but dead-ends — a client following the pointer finds no authorization-server document there and the flow dies at discovery, before sign-in. The AuthKit domain moved to accounts.mukoko.com in the Aug 2026 migration; the previous host identity.nyuchi.com has had no DNS record since, so anything still naming it is broken rather than merely stale.

Landed

• Hosted sign-in (AuthKit) — the sign-in doctrine: one WorkOS environment, per-app AuthKit applications, required MFA on the hosted page, the shared session that gives continuous sign-in across apps, the Next.js integration pattern, and the per-app configuration checklist.

What needs to land here

• WorkOS setup — project layout, environments, the directory sync model.
• accounts.mukoko.com — allowed redirect origins, branded login, and the /.well-known/ endpoints the AuthKit issuer exposes.
• Organisations — the org model, org-scoped roles, how orgs map to billing and to Console plans.
• SSO — connecting customer IdPs (SAML / OIDC), domain claiming, the JIT-provisioning rules.
• JWT shape — the canonical Nyuchi JWT: claims, audience, issuer, short-lived access tokens vs. refresh, and the verification pattern every Nyuchi service implements.
• Service-to-service — machine identities, scoped tokens, and how background workers authenticate.

Cross-links (once content lands)

• nyuchi/mukoko-platform — the Console implementation that consumes these tokens.
• nyuchi/mzizi-tools — mzizi-cli helpers for verifying Nyuchi JWTs.
• bundu-labs/bundu-docs — the Mzizi authentication pattern, for client-side UX.