Rotate keys safely (aka: oh no)

Bissap has two different “keys” people mix up:

• bs_live_... = agent key (per user). The agent uses it to call your app.
• bss_... = sdkSecret (per project). Your server uses it to call Bissap Cloud.

This page covers how to rotate both.

Rotate an agent key (bs_live_...)

Mint (get) a new key (SDK-only)

Your backend exposes this when you use the SDK:

• POST /bissap/keys → returns a fresh bs_live_... once

Example:

curl -sS -X POST http://localhost:3000/bissap/keys \
  -H 'content-type: application/json' \
  -d '{"name":"my agent","scopes":["read","write"]}'

Notes:

• This endpoint is meant to be called from your app UI (profile/settings) while the user is signed in.
• The key should be shown once, then stored by the agent (not by your frontend).

Revoke the old key

Local mode (no dashboard): revoke it via your app (SDK route)

• DELETE /bissap/keys/:id

Your app can get :id by calling:

• GET /bissap/keys (lists keys for the signed-in user)

Hybrid/Cloud mode (dashboard visible): revoke from either place:

• Dashboard → Project → Keys → Revoke
• Or via your app UI using DELETE /bissap/keys/:id (still works)

“Rotation” recipe (works in any mode)

1. Mint a new key
2. Update the agent to use the new key
3. Revoke the old key (minting a new one does not revoke existing keys)

That’s it. No ceremony. (Keys are cheap. Panic is expensive.)

Rotate the project sdkSecret (bss_...)

Get the sdkSecret (first time)

In Hybrid/Cloud, you need a Cloud project.

• Dashboard → Create project → you’ll see the sdkSecret once
• Store it in your server env var / secret manager

Local mode doesn’t use an sdkSecret.

Rotate the sdkSecret

1. Dashboard → Project → Settings → Rotate sdkSecret
2. Update your server env var / secret store
3. Redeploy

Old sdkSecrets stop working immediately.

Pro tip

If you ever paste secrets into chat: rotate first, explain later.