The capability exposure/kill mechanism is fail-closed and covered by tests, but it is a platform operational control — not a self-service button per workspace today.
Besides the account-in-good-standing check (Suspension) and RBAC (Roles), the platform has a third layer: a capability resolver that decides whether an expensive/sensitive surface is exposed, limited, or shut down — with immediate effect in an emergency.
What it is#
A capability is a named surface that can be turned on/off orthogonally to the plan and delinquency. Groups:
| Group | Capabilities | Effect of shutting down |
|---|---|---|
| Money/consumption | consultas no console de dados, acesso ao conjunto de dados, amostragem de dados, dashboard refresh, consulta em linguagem natural, AI insights, export to Excel | severs the corresponding paid path |
| Exposure/isolation | api.v1 (external REST+OData API), public dashboard and embed (embed + public dashboard) | drops external exposure without touching internal data |
| Pilot (run) | ingestion run (pipeline), report run (generation/delivery of report) | nothing runs/enqueues/delivers |
| Organization | org.admin (org administration) | closes the org surface (per-org) |
How the decision is made (order)#
- Global kill (
*) → everything closed. - Kill by capability → that surface closed.
- Versioned config (envelope
{ v, items }) → rollout %, allowlist/denylist, override by org/workspace/user, expiration. - Default: a declared capability without a kill is born exposed. The resolver also knows how to treat a capability marked as sensitive — that one is born OFF without an explicit decision (fail-closed) — but today no capability in the catalog is marked as such, by a decision recorded in code: marking one would leave it turned off for everyone, and the delinquency barrier is another layer (Suspension). In other words: the effective default today is "exposed", and control happens via shutdowns and limits, not via a baseline off.
On top of everything, an emergency shutdown overrides last — emergency always wins, including over a custom config.
Fail-closed is the rule#
- Unreadable config (invalid JSON) → the capability closes (configuration error), never "opens in the dark".
- Sensitive capability without a decision → OFF (mechanism tested; not used in the current catalog, as explained above).
- Immediate effect, no redeploy, when the operator triggers the emergency.
Use cases#
- Contain an incident: shut down the external API or the public embed immediately, without bringing down the whole app.
- Safe rollout: expose a capability to a fraction (canary) before 100%.
- Isolate exposure: killing
api.v1/public dashboard and embed cuts egress without affecting those who only use the internal BI.
Scope and permissions#
- Admin view: the effect of capabilities is visible to the workspace (a surface disappears/responds unavailable).
- Control: the actuation (kill/canary/rollout) is operational/platform — not a per-workspace toggle today.
Example#
During an incident, the operator triggers the kill for api.v1. From then on, every call to /api/v1/** responds unavailable — but the internal dashboards of Comércio Aurora (fictional) remain live, because internal data was not touched. Once the incident is resolved, the capability is exposed again.
Expected outcome#
- Capability exposed → works normally (the account-in-good-standing check still applies).
- Capability shut down → the surface responds unavailable predictably; the rest of the product continues.
Relation to other checks#
- RBAC decides what a role can do (403 from role).
- Account-in-good-standing check decides if the account is current (402 for delinquency).
- Capability / shutdown decides if the surface is exposed (independent of the other two). They are orthogonal layers.
Security#
- Fail-closed at every edge (invalid/sensitive config → OFF).
- Decision by org has cache isolated by
orgId— one org's decision never leaks to another. - Emergency kill does not depend on a redeploy.
Limits#
- Not a self-service dashboard per workspace: our team makes the adjustment.
- The exposure kill (
api.v1/public dashboard and embed) is orthogonal to delinquency — it does not substitute subscription checks nor RBAC.
Common errors and how to fix them#
| Symptom | Likely cause | What to do |
|---|---|---|
| API/OData responding unavailable | capability api.v1 shut down (incident) | follow the status; open a ticket |
| Embed/public dashboard down | capability public dashboard and embed shut down | same as above |
| Refresh/AI/export down, but dashboard opens | consumption capability shut down (not delinquency) | check with support |
| Feature "disappeared" without payment notice | capability kill ≠ 402 suspension | differentiate from Suspension |
Related#
Last review: 2026-09-08.
Last reviewed: 2026-09-08.