Security
How authentication, authorization, and key management work in Bissap.
Auth model overview
Bissap uses scoped API keys to authenticate agent requests:
| Layer | Mechanism | Used by |
|---|---|---|
| User auth | Your app's existing auth (via userResolver) | Logged-in users minting/managing keys |
| Agent auth | API keys (bs_live_..., per-key, scoped) | AI agents calling intents |
| SDK auth | sdkSecret (bss_..., per-project) | Your backend talking to Bissap Cloud (hybrid/cloud mode only) |
Each layer has different trust boundaries. API keys are scoped and individually revocable. The SDK secret is long-lived and grants project-level access.
DO NOT EXPOSE BISSAP_CLOUD_SDK_SECRET
The SDK secret must never appear in client-side code, browser bundles, public repositories, or logs. Keep it exclusively in server-side environment variables.
Key revocation
Revoke a compromised or unused API key:
- Local mode:
DELETE /bissap/keys/:idfrom your app - Hybrid/Cloud mode: revoke from the dashboard or via your app
In Cloud and Hybrid modes, revocation is authoritative and persistent. See Key rotation for the full workflow.
Rate limiting
The SDK enforces per-key rate limits in memory. Exceeding the limit returns 429 RATE_LIMITED.
Intent-level access control
Bissap enforces access at the intent level, not the route level:
- Unregistered intents don't exist. Calling an unregistered intent returns
404 INTENT_NOT_FOUND. - Intent discovery only shows registered intents.
GET /bissap/agent/intentscannot leak unregistered functionality. strictIntents: true(recommended) ensures unknown intents are always rejected, even if you have anonAgentIntentfallback.
Intent oversharing is a security risk.
The most common mistake is exposing bulk-data intents that let agents scrape proprietary data in a single call. Scope intents to individual user data, not bulk exports.
See: Intent Hygiene guide