Skip to content
Nyuchi Docs

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

Section titled “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

Section titled “Flow”

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

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

    Terminal window
    GET /v1/auth/workos/login?return_to=https://your-app.example/auth/callback

    return_to is validated against an allowlist—see Third-party apps: register your redirect origin below. A relative path or an unregistered origin gets a 400, not a redirect—this is a public, multi-tenant endpoint, so it never redirects a freshly minted token somewhere unverified.

  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=…

    If return_to was never supplied (or WorkOS didn’t round-trip it), this endpoint returns a 400 instead of the token—it does not fall back to rendering the JWT in the response body unless the caller explicitly opts in with allow_direct_token_response=true. Never do that from a browser: a live access token would render in plain text on screen and land in browser history. That opt-in exists only for scripted, server-to-server code-exchange flows.

  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.

Third-party apps: register your redirect origin

Section titled “Third-party apps: register your redirect origin”

/v1/auth/workos/login is shared across every app built on the Nyuchi API—the gateway doesn’t hardcode any single app’s domain into its return_to allowlist. Instead, each app registers its own redirect origins on its API key:

Terminal window
curl -X PATCH https://api.nyuchi.com/v1/api-keys/{key_id}/redirect-uris \
  -H "Authorization: Bearer $PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris": ["https://your-app.example/auth/callback"]}'

Then pass that key’s client_id alongside return_to:

Terminal window
GET /v1/auth/workos/login?return_to=https://your-app.example/auth/callback&client_id=nyk_...

The gateway checks return_to’s origin against that key’s registered redirect_uris, not a global list—so onboarding a new app never requires a gateway config change. Omitting client_id only works for origins on the gateway’s first-party allowlist (the Nyuchi console itself); every other app must pass it.

Configure

Section titled “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

Section titled “Sign out”

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

Using the platform JWT

Section titled “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.

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

There’s no refresh endpoint—the token is valid for 30 days (1 year for native clients). When it expires, send the user through /v1/auth/workos/login again; AuthKit’s own session usually makes that instant with no re-prompt.

Next steps

Section titled “Next steps”