Apps

An App is a per‑workspace logical surface: a chatbot, a RAG assistant, a code agent. Each App owns its own thresholds, detectors, custom PII rules, custom phrases, tool policy, privacy mode, custom event params, dataset projection, and per‑App quotas. Every scan and proxy call is attributed to exactly one App via the X-Blindsight-App-Id header.

Why Apps

One workspace usually fronts several distinct LLM surfaces that warrant different security postures:

A healthcare chatbot needs strict PHI thresholds and may forbid certain providers.
An internal code agent can tolerate looser injection thresholds but needs strict tool policy.
A customer support bot wants standard thresholds and rich ticketing custom params.

Apps let one workspace run all of these under one license without their settings bleeding into each other, and keep their event streams cleanly separable in analytics.

Managing Apps

Apps are managed under Runtime Security → Apps in the dashboard, or via the REST API.

Method	Path	Notes
`GET`	`/api/runtime-security/apps/templates`	List built‑in templates.
`GET`	`/api/runtime-security/apps`	List Apps in the caller’s workspace.
`POST`	`/api/runtime-security/apps`	Create an App (optionally from a template).
`GET`	`/api/runtime-security/apps/{id}`	Read one App.
`PATCH`	`/api/runtime-security/apps/{id}`	Update App‑level metadata, status, quotas.
`DELETE`	`/api/runtime-security/apps/{id}`	Soft‑delete (archive).
`POST`	`/api/runtime-security/apps/{id}/clone`	Clone an existing App.
`GET`	`/api/runtime-security/apps/{id}/config-versions`	List versioned config history.
`PUT`	`/api/runtime-security/apps/{id}/config`	Publish a new config version.
`GET / POST / PATCH / DELETE`	`…/apps/{id}/custom-params[/{param_id}]`	Manage typed custom event params.
`GET / POST / DELETE`	`…/apps/{id}/tokens[/{token_id}]`	Manage signed App tokens.
`GET`	`…/apps/{id}/dataset/summary`	Event count + dataset projection.
`GET`	`…/apps/{id}/template-diff`	Drift between this App and its source template.

Built‑in templates

Cloning a template is the fastest way to get a production‑shaped App. Each template ships with sensible thresholds, a starter custom‑phrase list, custom PII rules where appropriate, custom params, and dataset field picks.

Template key	Use case	Highlights
`healthcare_chatbot`	Patient‑facing PHI traffic	Tighter thresholds (block 0.75 / redact 0.45), Swiss AHV / ICD‑10 / dosage rules.
`rag_assistant`	KB / retrieval‑augmented apps	Strong injection defence on retrieved docs, RAG‑specific custom phrases, retrieval params.
`code_agent`	Coding assistants with shell / SQL	Strict tool denylist, agentic guardrails on, secret detection.
`customer_support_bot`	General support assistants	Standard thresholds, ticket / CSAT custom params.

App resolution headers

Header	Required	What it does
`X-Blindsight-App-Id`	Always	App UUID. The call is rejected with `400 APP_ID_REQUIRED` if missing.
`X-Blindsight-App-Token`	Only when the App has `require_signed_token=true`	Plaintext token issued via `…/apps/{id}/tokens`. Verified for signature and against the live token row.

Status code	When
`423 APP_DISABLED`	App `status="disabled"`.
`410 APP_ARCHIVED`	App was archived or deleted.
`429 APP_QUOTA_EXCEEDED`	`max_events_per_hour` / `max_events_per_day` hit. Includes `Retry-After`.

Privacy modes

Set per‑App via privacy_mode on create or update.

Mode	What dashboard users see
`redacted_only`	Only the `redacted_text` is ever shown. Default.
`both_role_gated`	Original text visible only to roles with the dataset‑PII view capability.
`hashed_pii`	PII spans replaced with stable salted hashes, joinable across events without exposing the secret.
`user_choice`	The caller picks per‑event via the `privacy_mode` metadata field.

Use hashed_pii when you need to count distinct PII values (for example “how many unique email addresses leaked this week”) without exposing the values themselves.

Custom event params

Each App declares typed event params (string / number / boolean / date / enum). When you call /scan/input or /scan/output, attach a custom_params object; values are validated against the App’s schema and stored on the event row for downstream filtering and dataset export. Required params reject the scan with 400 CUSTOM_PARAM_REQUIRED if missing.

{
  "text": "patient asked about ICD-10 J45.9",
  "custom_params": {
    "patient_language": "de",
    "contains_dosage": false
  }
}

Versioned config

Every config write creates a new config_version_number linked to the event row that produced it.

GET …/apps/{id}/config-versions returns the change history.
change_summary captures the operator’s reason for the change.
The drift dashboard reports on config‑version transitions, so a sudden change in verdict mix can be correlated to a config change.

Common workflows

Set up a staging clone of a production App

POST .../apps/{id}/clone on the production App.
Rename the clone staging_<original>.
Lower its max_events_per_hour so a misconfigured client can’t burn quota.
Point your staging environment at the clone’s X-Blindsight-App-Id.

Roll out a tighter PII threshold safely

Note the current config version on the App.
PUT …/apps/{id}/config with the new thresholds and a change_summary like tightening EU launch.
Watch the drift dashboard for verdict mix changes over the next 24 hours.
If anything looks wrong, PUT the previous config version back; the history endpoint lets you roll back precisely.

Use signed tokens for hardened deployments

Set require_signed_token=true on the App.
Mint a token via POST .../apps/{id}/tokens.
Distribute the token to your edge clients.
Rotate tokens by minting a new one alongside the old, then deleting the old after the rotation window.

Getting started

Data Integrity

Runtime Security

DLP (endpoint)

Why Apps

Managing Apps

Built‑in templates

App resolution headers

Privacy modes

Custom event params

Versioned config

Common workflows

​Why Apps

​Managing Apps

​Built‑in templates

​App resolution headers

​Privacy modes

​Custom event params

​Versioned config

​Common workflows

Why Apps

Managing Apps

Built‑in templates

App resolution headers

Privacy modes

Custom event params

Versioned config

Common workflows