Local vs Hybrid vs Cloud

Bissap has 3 key management modes. The difference is where keys are stored and validated, not how they're created.

In all three modes, keys are minted the same way: your app calls POST /bissap/keys (via the SDK). The user authenticates in your app, your app mints a key, the user gives it to their agent. The app owner picks the mode.

Local (fastest)

• Storage + validation: your app (memory or storage adapter)
• Dashboard: does not show keys
• Great for demos, self-hosters, and "I want zero dependencies."

What your users will experience

"Connect your agent" → your app generates a key → show it once → user pastes it into their agent.

If they lose it: generate a new one. (This is your app's version of "we don't do password recovery.")

Revoking happens via your app UI (profile/settings), because only your app knows the local key list.

Hybrid (recommended)

• Storage + validation: your app cache + Bissap Cloud (local first, cloud fallback)
• Dashboard: shows keys + revocations
• Best UX and you get a Cloud-backed kill switch.

What your users will experience

Same flow as Local:

"Connect your agent" → key is shown once → paste into agent.

But now you (the builder) can see + revoke keys in the dashboard, and revocation stays enforced even if your app restarts.

Deployment tip (Cloud Run / Functions): IAM is per service. Prefer two services (public /bissap/agent/*, private /biscap/keys) or a gateway. One public service also works if /bissap/keys is enforced by your app auth and org policy allows allUsers, but splitting is tighter.

Platform quick notes

• Cloud Run / Cloud Functions: per-service IAM → two services (public /agent/*, private /keys) or an HTTP gateway with path rules.
• API Gateway / ALB / Nginx: path-based auth is fine; one service is enough—block /keys at the edge.
• Vercel / Netlify / plain Node server: expose /agent/*, keep /keys behind session auth. Avoid double-prefixing (/bissap/agent once).

Cloud

• Storage + validation: Bissap Cloud only
• Dashboard: the source of truth
• Useful when you want ops/support control (or you're managing access like a grown-up… reluctantly).

Security footgun prevention: key minting + validation always happen on the server. Never put secrets or minting endpoints in the browser/mobile client.

What your users will experience

Same flow as the other modes:

"Connect your agent" → your app mints a key via the SDK → show it once → user pastes it into their agent.

The difference is that your app doesn't store the key. Cloud does. You (the builder) get full visibility and control in the dashboard.

Failure handling

Bissap is designed to degrade gracefully when Bissap Cloud is unreachable.

Startup: enableAgentAccess() never blocks on Cloud connectivity. Your app boots normally regardless of Cloud status. Intent manifest uploads are fire-and-forget.

Hybrid mode under Cloud outage:

• Key minting (POST /bissap/keys) falls back to local storage. Keys created during an outage exist locally and work immediately.
• Key revocation falls back to local storage.
• Key validation uses local-first lookup. Local keys continue to work. Cloud-issued keys will fail to validate (fail-closed, not fail-open).
• Intent discovery and execution work normally (intents are defined in your code, not fetched from Cloud).
• Usage and violation reporting silently skip. No retries, no queuing, no backpressure.

What this means in practice: if Cloud goes down, your app keeps running. Local keys work. Cloud keys don't. No hangs, no crashes, no memory leaks.

Cloud mode under Cloud outage: all key operations fail (there is no local fallback). This is by design: cloud mode means Cloud is your only storage.

If you're unsure: start Hybrid.

Important: use strictIntents: true

Regardless of mode, always set strictIntents: true in production. This ensures:

• Only registered intents can be called (unknown names → 404)
• Intent discovery only shows what you've explicitly defined
• No fallthrough to onAgentIntent catch-all handlers

Without it, an agent could potentially call intent names that bypass your registry and hit a generic handler, which may expose more than intended.

See: Intent Hygiene for guidance on choosing which intents to register.