Keys & scopes (the “who” and the “how much”)

Bissap has two kinds of secrets. Treat both like passwords.

Never trust the client. Anything involving key minting (/bissap/keys), key validation/auth middleware, or intents that touch user data must run server-side (backend/serverless), not in the browser/mobile app.

Secrets live server-side only. bss_... (sdkSecret) + DB creds go in server env vars / a secret manager. The browser should only ever see NEXT_PUBLIC_* variables (and none of those should be secrets).

• bs_live_...: agent key (per user). This is what the agent uses to call your app.
• bss_...: sdkSecret (per project). This is what your server uses to talk to Bissap Cloud.

If you paste either into a group chat, congratulations: you just invented Key Rotation Day.

What your users will experience (by mode)

• Local: user connects their agent inside your app → you show the key once → your app UI is also where revocation happens.
• Hybrid: same in-app “connect” flow, but you also get a Cloud kill switch + dashboard visibility for revocations.
• Cloud: keys are typically created/rotated in the dashboard, so your app UX becomes more “paste a key” (unless you build a minting flow that calls Cloud).

(Full version: Local vs Hybrid vs Cloud.)

How you get keys (using the SDK)

Agent keys (bs_live_...), minted by your app

When you call enableAgentAccess(app, ...), the SDK mounts:

• POST /bissap/keys: mint a new agent key (returned once)
• GET /bissap/keys: list keys for the signed-in user
• DELETE /bissap/keys/:id: revoke a key

This is designed for an in-app “Connect your agent” screen (Profile → Settings → Connect).

Project sdkSecret (bss_...), minted by Bissap Cloud

You only need this in Hybrid/Cloud modes.

• Create a project in the dashboard → you’ll see an sdkSecret once
• Store it server-side (env var / secret manager)

Local mode doesn’t need an sdkSecret.

Scopes

Scopes are short strings (e.g. read, write) that limit what a key can do.

In the simplest setup:

• a read key can run read-only intents
• a write key can run writey intents

Revocation (the panic button)

Revocation is the feature you think you don’t need until you really, really need it.

• If a bs_live_... key leaks → revoke it.
• If a bss_... sdkSecret leaks → rotate it (project settings).

Cloud/Hybrid modes make revocation immediate and visible in the dashboard.