Violations & enforcement

Violations are records of scope enforcement failures, validation errors, and policy breaches detected by the Bissap SDK at runtime. Every time an agent key attempts an action it is not authorized for, or fails intent validation, the SDK reports a violation to Bissap Cloud.

What gets recorded

Each violation captures:

• Key ID and user ID of the agent key involved
• Intent that triggered the violation (if applicable)
• Kind of violation (e.g. FORBIDDEN_SCOPE, INTENT_VALIDATION_ERROR, RATE_LIMITED, POLICY_BLOCKED)
• Severity: info, warning, or severe
• Message with a human-readable description
• Metadata (arbitrary JSON with extra context)
• Timestamp of when the violation occurred

Auto-revoke

Bissap Cloud can automatically revoke agent keys that accumulate too many severe violations. This is configured per project in the dashboard under project settings.

You set two values:

• Threshold: the number of severe violations within the window before auto-revoke triggers
• Window: the time period to count violations in (defaults to 24 hours)

When a key reaches the threshold, it is immediately revoked and an audit log entry is created. Violations with severity severe or kind in FORBIDDEN_SCOPE, INTENT_VALIDATION_ERROR, RATE_LIMITED, POLICY_BLOCKED count toward the threshold.

Querying violations via API

Use GET /v1/sdk/violations to retrieve violations for your project. Authenticate with the same SDK secret and project header used by other /v1/sdk/* endpoints.

Query parameters:

Response:

{
  "violations": [
    {
      "id": "...",
      "keyId": "...",
      "userId": "...",
      "intent": "...",
      "kind": "FORBIDDEN_SCOPE",
      "severity": "severe",
      "message": "Key attempted scope 'admin:write'",
      "metadata": {},
      "createdAt": "2026-02-15T12:00:00.000Z"
    }
  ],
  "total": 42
}

Results are ordered by timestamp, newest first. See the API reference for full details.