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

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.