Authentication

The Nyuchi API accepts a single bearer token—an HS256 platform JWT—on every authenticated user request. All authentication is handled by WorkOS AuthKit: it hosts the sign-in UI and the gateway exchanges the result for the platform JWT. For server-to-server and programmatic access, use API keys instead—client ID and secret pairings managed in the console.

Every sign-in resolves to the same person record and the same JWT shape (sub is the person id), so downstream code never needs to know how the user signed in.

WorkOS AuthKit

WorkOS AuthKit hosts the sign-in UI, handles passwordless email, social logins, and enterprise SSO, and hands you a one-time code your backend can exchange for a session. The Nyuchi backend wraps that exchange so your client only has to follow a redirect and read a URL fragment.

Flow

1. Send the user to /v1/auth/workos/login

   Pass a return_to query parameter so the backend knows where to drop the user after sign-in. The endpoint responds with the hosted AuthKit URL.

   GET /v1/auth/workos/login?return_to=/auth/workos/callback

2. WorkOS posts back to the backend

   AuthKit redirects to WORKOS_REDIRECT_URI with a short-lived code. The backend exchanges it for WorkOS user details, upserts the person record keyed on workos_user_id (falling back to email for pre-WorkOS accounts), and mints a platform JWT.

3. The backend redirects the browser with the token in the fragment

   The token never appears in server logs because it sits in the URL fragment, which browsers strip from Referer and which the backend never sees.

   302 /auth/workos/callback#access_token=…&person_id=…

4. Your client consumes the fragment

   Parse window.location.hash, store the token, and clean the fragment from the URL so a refresh does not re-process it. The console exposes this as consumeWorkOSCallback() on the auth context.

Configure

Set four environment variables on the backend. Until all four are populated, /v1/auth/workos/* returns 503 Service Unavailable, so you can deploy the code path before turning the feature on.

Variable	Purpose
WORKOS_API_KEY	Server-side secret from the WorkOS dashboard.
WORKOS_CLIENT_ID	Identifies the AuthKit application.
WORKOS_REDIRECT_URI	Where AuthKit returns the user. Must point at /v1/auth/workos/callback.
WORKOS_COOKIE_PASSWORD	32+ character secret used to seal session cookies.

Sign out

POST /v1/auth/workos/logout revokes the WorkOS session. Clear the local token afterwards so subsequent requests are unauthenticated.

Note

A legacy email-OTP flow still exists under /v1/auth/otp/* for accounts created before the WorkOS cutover. It mints the same platform JWT and is being retired—do not build new integrations against it.

Using the platform JWT

Send the token as a bearer credential. The same token works for every /v1/* namespace, because it carries the person id in sub.

curl https://api.nyuchi.com/v1/identity/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Call POST /v1/auth/refresh before the token expires to obtain a new one without forcing the user back through AuthKit.

Next steps

• Review the API overview for the full list of namespaces.
• Create API keys in the console for programmatic access.
• Read security and rate limits before going live—/v1/auth/exchange and /v1/auth/refresh are rate limited per IP.