App Enablement

Vibecoding tools give you a frontend, then stop at the hard part: real login and a backend that enforces who can see what. App Enablement is how Orkestia closes that gap. Your app stays where it is. Orkestia hosts login, issues the user JWT, and runs only the workflows you expose — scoped to that user.

Three things to do on this page: open the OAuth SDK, follow enable and use, or paste the agent prompt and let an MCP-connected agent provision the app for you.

OAuth SDK

@orkestia/auth is the browser PKCE / OAuth SDK for your app's users ("Sign in with Orkestia"). No client secret. The public client_key is safe in frontend source.

npm i github:orkestia/orkestia-auth-sdk

Early access (v0.0.x). npm i @orkestia/auth will work once the package is on the registry.

Enable and use

1. Provision — identity.app.provision returns a public client_key and the OIDC bundle.
2. Install — @orkestia/auth (npm i github:orkestia/orkestia-auth-sdk).
3. Wire login — signIn() on the button, handleCallback() on the registered redirect.
4. Call as the user — send session.token as a Bearer. Never put an org token in the browser.

1. Provision the identity app

An org member — or an agent on the Orkestia MCP — runs one workflow. Pass only the app name and callback URLs. You never pass organization_uuid or actor; the server fills those from the token.

To claim an App Host site, the app must be live (identity.app.set-mode). Dev apps stay on localhost.

identity.app.provision({
  name: "My App",
  redirect_uris: [
    "http://localhost:5173/callback",
    "https://myapp.com/callback",
  ],
})
// → { client_key, client_uuid, identity_app_uuid, redirect_uris,
//     integration: { issuer, discovery_url, authorize_url, token_url, jwks_url, flow, sdk } }

Registered redirect_uris are accepted immediately — there is no manual CORS step. Add more later with identity.app.configure-client. Full contract: Sign in with Orkestia.

2. Install the OAuth SDK

npm i github:orkestia/orkestia-auth-sdk

See Auth SDK for renew, verify, and config defaults (login.orkestia.dev, workflow-api.orkestia.dev).

3. Wire Sign in with Orkestia

import { createOrkestiaAuth } from "@orkestia/auth"

const auth = createOrkestiaAuth({ clientKey: "orkestia_…" }) // from provision

await auth.signIn()                    // login button → hosted login
const session = await auth.handleCallback() // /callback → RS256 JWT
const current = auth.getSession()      // { token, email, endUserUuid } | null
auth.signOut()

signIn() builds the PKCE challenge and redirects to login.orkestia.dev. After the user authenticates, Orkestia returns to your registered redirect_uri with a one-time ?code. handleCallback() exchanges it for the token. The token never appears in a URL.

4. Call Orkestia as that user

Pass session.token as Authorization: Bearer … to the Node or Python workflow SDK, or to REST. Never put an org-member token or API token in the browser.

The engine injects the end-user principal immutably. The user can start only virtual workflows you exposed — and only their own App Data rows.

Paste this into your agent

Copy the block below into Cursor, Claude, or any MCP-capable agent. The agent provisions the identity app in your Orkestia org and wires @orkestia/auth in this repo.

You need the Orkestia MCP connected (https://mcp.orkestia.dev/mcp) with a token from Settings → API tokens. If the agent is not connected, it will stop and tell you.

Configure Sign in with Orkestia for this app.

You are connected to the Orkestia MCP (https://mcp.orkestia.dev/mcp).
If you are not, stop and tell me to connect it first:
https://docs.orkestia.dev/reference/mcp-integration

1. Call whoami() first. Do not ask me for organization_uuid.
2. If the MCP exposes rule://orkestia-auth-setup, read it.
3. Ask me only for the app name and callback URLs
   (include http://localhost:<port>/callback if I am developing).
4. Start identity.app.provision with those values. Wait until it completes.
   Pass only name and redirect_uris — never organization_uuid or actor.
5. From the terminal output, take client_key and the integration bundle.
6. Install the OAuth SDK:
   npm i github:orkestia/orkestia-auth-sdk
   Docs: https://docs.orkestia.dev/sdks/auth
   Source: https://github.com/orkestia/orkestia-auth-sdk
7. Wire createOrkestiaAuth({ clientKey }) in this codebase:
   - signIn() on the login button
   - handleCallback() on the registered redirect_uri
   - getSession() anywhere later
8. Never put an org-member token or API token in the browser.
   client_key is public (PKCE).
9. Tell me the client_key, registered redirect_uris, and the files you changed.

The shape of an Orkestia app

Your frontend  ──►  Sign in with Orkestia  ──►  end-user JWT
     │
     └──►  invoke an exposed workflow with that JWT
                     │
                     └──►  Orkestia runs it scoped to the user → only their data

Your app has no backend of its own and never holds a database credential. It authenticates the user, then asks Orkestia for that user's data.

Go deeper