Sign in with Orkestia
"Sign in with Orkestia" is a hosted login (at login.orkestia.dev) your app redirects to. It runs a standard PKCE authorization-code flow and returns an RS256 JWT your app verifies locally against the published JWKS. Your app never sees a password and stores no secret — the public client_key is safe in browser source.
identity.app.provision and wires @orkestia/auth.1. Provision an app
One call returns your client_key and every endpoint you need:
identity.app.provision({
name: "My App",
redirect_uris: ["http://localhost:5173/callback", "https://myapp.com/callback"],
})
The redirect_uris you register are accepted immediately — there is no manual CORS step. To add more later, call identity.app.configure-client.
New apps default to mode=dev (localhost-only redirects, a small email allow-list). Pass mode: "live" to provision a production tenant directly, or graduate later with identity.app.set-mode. App Host claim and publish require live. The live switch is one-way; leftover localhost URIs are rejected by name.
2. Wire the flow
Use the @orkestia/auth browser SDK (PKCE / OAuth — install npm i github:orkestia/orkestia-auth-sdk, or copy its ~120 lines inline):
import { createOrkestiaAuth } from '@orkestia/auth'
const auth = createOrkestiaAuth({ clientKey: 'orkestia_…' })
// On your "Sign in" button:
await auth.signIn() // PKCE redirect to the hosted login
// On your /callback page:
const session = await auth.handleCallback() // exchanges ?code → RS256 JWT
// Anywhere:
const current = auth.getSession() // { token, email, endUserUuid } | null
auth.signOut()
That's the whole integration. signIn() builds the PKCE challenge and redirects; after the user authenticates, Orkestia returns to your redirect_uri with a one-time ?code, and handleCallback() exchanges it for the token. The token never appears in a URL.
The contract
The provision bundle's integration URLs point at these endpoints — the live contract:
| Step | Endpoint |
|---|---|
| Authorize (redirect) | GET https://login.orkestia.dev/authorize?client_key&redirect_uri&state&code_challenge&code_challenge_method=S256 |
| Token exchange | POST https://workflow-api.orkestia.dev/api/auth/end-user/token → { token } |
| Verify (JWKS) | GET https://workflow-api.orkestia.dev/api/auth/end-user/jwks (RS256, iss=login.orkestia.dev) |
| Register / verify-email / password-reset / MFA | under https://workflow-api.orkestia.dev/api/auth/end-user/* |
Org members vs end-users
Two distinct identities — don't confuse them:
Org members
Your team — Cognito-backed, manage the org, run any workflow. See User Onboarding.
End-users
Your app's users — Orkestia's own store, "Sign in with Orkestia," seat-gated, can only run workflows you expose to them.
Next: full Auth SDK reference (silent renew, verify, config), then App Data / End-user data.