The Settings page holds the settings that apply to the whole organization and the K-Block identities that sign on its behalf. Every member can open it; what each person can change depends on their role.
An On this page list next to the cards links to each section and shows its state at a glance: whether observe mode is on, what agents see, and whether the organization principal is set.
Settings at a glance
| Setting | Default | Who can change it | When it takes effect |
|---|---|---|---|
| Name | Set at creation | Owners, admins | At once |
| Default approval lifetime | 86,400 seconds (24 hours) | Owners, admins | For decisions made after the change |
| Longest observe window | 0 hours (observe off) | Owners only | At once; can end open windows |
| Live opt-in for observe windows | Not given | Owners only | At once; withdrawing it ends open windows |
| What agents see of a decision | Rule and approval details | Owners, admins | For decisions made after the change |
| Organization principal | Not set | Owners only | At once |
| Data retention | The plan's period | Owners only, with the Cloud API | At the next retention run |
Other members see the current values with a note such as "Only owners and admins can change organization settings." Management API keys can never change settings. Every change is recorded in the audit log.
Organization
The Organization card holds two settings and three read-only facts.
- Name: the organization's display name, one line of up to 200 characters.
- Default approval lifetime (seconds): how long an approval request stays open when the policy rule that asked for approval does not set its own lifetime. The same lifetime also limits how long an allowed call can still be executed after its decision. Enter 60 to 2,592,000 seconds (1 minute to 30 days); the hint under the field shows the value in words.
- Organization ID, Slug and Created: shown for reference. The slug is chosen when the organization is created and cannot be changed here.
Select Save. The page confirms with "Saved."
The lifetime applies to approval requests created after you save; requests already open keep the expiry they were created with. A request never outlives the delegation the agent acts under, whatever the lifetime. See How approvals work.
Observe mode
Observe mode lets one agent's calls run for a limited time while its policy's decisions are only recorded, for example while you onboard an agent and tune its policy. Explicit deny rules, guards and delegations are always enforced, even during a window.
Observe windows are started per agent by owners and admins on the agent's page. These two settings decide whether that is possible at all, and only an owner can change them:
- Longest observe window (hours): 0 (the default) turns observe off. At most 168 hours. A window can never be extended.
- Allow observe windows (the live opt-in): every window needs it, including windows that cover only test keys, because test and live gateway keys reach the same tools, upstreams and credentials.
The card's badge sums up the state: Off, No live opt-in (a longest window is set, but no window can start), or On · up to a number of hours.
Select Save observe settings. Before saving, the card says what the change does:
| Change | Effect when you save |
|---|---|
| Turn observe on, give the live opt-in, or raise the longest window | A warning, This widens what can run: you must check I understand, and relaxed calls will be reviewed before you can save |
| Set the longest window to 0 | Observe is off and every open window ends now |
| Withdraw the live opt-in | Every open window ends now, test-only windows included, and no new window can start |
| Lower the longest window | Every open window longer than the new maximum ends now |
The banner at the top of every organization page shows open observe windows. Ending windows here is recorded as organization.observe_settings_changed. An admin who tries to change these settings through the API gets OWNER_REQUIRED.
What agents see of a decision
When the Gateway refuses a call or holds it for approval, the agent receives an explanation. This card sets the organization's ceiling for how much of it agents see. A policy can show less, never more (see What agents are told).
| Option | Agents see at most |
|---|---|
| Refusal only | Only the refusal; its text still names the deciding rule, its effect and the candidate rules, and an approval request's ID and expiry |
| Rule and approval details (default) | The deciding rule and its description, the approval's roles, approver count and time limit, but no condition values or amount band |
| Rule and thresholds | The rule and its thresholds |
People always see the full explanation in the dashboard and through the Cloud API. Webhooks carry the reason code, message and policy fields, not the explanation.
Owners and admins choose an option and select Save. The change applies to decisions made from then on; recorded decisions keep what they recorded.
Organization principal
The organization principal is your organization's own K-Block identity. Agents act only with authority it delegates: its private key signs agent delegations, their revocations and action cancellations. K-Block Cloud stores only its public identity; the private key is kept in the browsers where it was generated or imported (and in key backups), and owners and admins sign there with the copy their own account holds. See Identities and KIDs.
Until a principal exists, no agent can be authorized. The page then shows No organization principal yet at the top.
Generate the principal
As an owner, select Generate principal in this browser in the Organization principal card. The private key is generated in your browser and never sent to K-Block Cloud.
Back up the key
The key exists only in this browser. Export a key backup on your account page (see Your account) so you can sign from another browser and do not lose the key.
Once set, the card shows the Principal KID and whether its key is in this browser (Key in this browser: Available, Not available or Unknown). It is Available only when your own account generated or imported the key in this browser. Without the key, delegations, revocations and cancellations cannot be signed in that browser. What the card says then depends on your role:
- Owner or admin: "Your account holds no copy of the principal's private key in this browser, so you cannot sign delegations, revocations or cancellations here." A copy that another K-Block account stored in the same browser profile is not used for you; the card then adds "This browser profile holds a copy stored for another K-Block account; it is not used for you. If you imported that copy yourself earlier, import the key backup again." Import a key backup that contains the principal, or ask an owner who has one. If nobody has the key any more, or it may be exposed, an owner replaces the principal.
- Approver, developer or viewer: "Owners and admins sign delegations, revocations and cancellations with the principal; your role does not use its key."
Unknown means that this browser's key storage could not be read, so the card cannot tell whether your copy of the key is here. It is not the same as having no copy. The card then shows the error "This browser's key storage is not available, so it cannot be checked for the principal's key". Close other dashboard tabs and reload the page. If it stays, check that the browser lets this site store data: some private windows and privacy settings block it.
When your account holds the key here, the card says "The key stays in this browser after you sign out. Before you leave a shared or borrowed computer, make sure a key backup exists somewhere other than this computer, then remove the key from this browser." and offers Remove from this browser…. It deletes this browser's copy of the key and changes nothing in K-Block Cloud: the principal stays your organization's principal. Without another copy (a key backup or another browser), nobody can sign delegations, revocations or cancellations any more, and an owner must replace the principal. Removing a copy is not a substitute for replacing a principal whose key may be exposed.
Replace the principal
Owners can open Replace the principal and select Replace principal…, then confirm. A new principal is generated in your browser and replaces the current one; the current principal's key is not needed. The card lists what happens before you confirm.
Replace the principal when nobody has its key any more, and also when its key may be exposed: a lost or stolen device held it (see If you lose a device), a backup containing it may have been read together with its passphrase, it was stored on a computer you do not control, or someone who should no longer have it holds a copy.
If the principal's identity documents conflict (it has equivocated), the card says that the principal is permanently invalid, and an owner replaces it there the same way.
Data retention
K-Block Cloud keeps the data of each protected action for your plan's retention period (30, 90, 365 or 730 days, unlimited on Enterprise; see Billing), or for the shorter period an owner chose. Once an action ended longer ago than that:
- Operational data is removed: the call's arguments kept beside the decision, the error details, the upstream tool's result kept for repeated calls, and webhook events (with their deliveries) older than the period, unless a delivery is still pending.
- Hosted evidence is removed too, once the action's authorization window is also over: its signed objects (which contain the exact arguments the call was decided on and the signed result), its receipt bundle, and the verification reports stored with the receipt.
- A minimal record stays: the action's decision (effect, policy version, amount), its status and outcome, its digests and identifiers (arguments digest, request fingerprint, idempotency key; the receipt's IDs and outcome, and the SHA-256 and size of its bundle), the approval decisions and the usage counts. It holds no arguments, results or error texts. It is what keeps a repeated call with the same idempotency key from running twice and your monthly usage correct. Delegations, identities and the audit log are kept as well.
Actions that are still open (pending approval, approved, executing), and their approval requests, are never touched.
Exported receipts stay valid. How long K-Block Cloud hosts a receipt is not how long it stays valid: a .kbundle carries everything a verifier needs, so a bundle you downloaded stays independently verifiable offline after K-Block Cloud deleted its copy. Its SHA-256 matches the one in the minimal record. To keep a receipt for longer than the retention period, download its bundle before then (Download .kbundle on the receipt page, or GET /api/v1/orgs/<org-id>/receipts/<receipt-id>/bundle).
After the period, an action's page still shows its decision, approval, outcome and receipt record, and says Hosted evidence deleted after the retention period; its arguments are no longer shown (their digest is). The receipt page says Hosted copy deleted after the retention period, and the Cloud API answers the receipt, its bundle and its decision check with HTTP 410 and the code EVIDENCE_EXPIRED, with the receipt's IDs, outcome, SHA-256 and the time of the deletion: the hosted copy is gone, the receipt is not invalid. Repeating a call with the idempotency key of such an action still returns its outcome and IDs, without the upstream's result, and never runs it again.
Owners can choose a shorter period for the organization, never a longer one than the plan's: send PATCH /api/v1/orgs/<org-id> with {"data_retention_days": 7} (1 to 3,650; null goes back to the plan's period). The change is recorded in the audit log as organization.retention_changed, and GET /api/v1/orgs/<org-id> shows the plan's period, the organization's own and the one in effect under data_retention. Admins and management API keys cannot change it. A shorter period applies within minutes, to actions that already ended longer ago than it: download the receipts you want to keep first. Each deletion is recorded in the audit log as retention.evidence_deleted (with counts only).
Personal identity
The Personal K-Block identity card is a summary of your own K-Block identity, which you need to approve requests and sign as yourself. You manage it, and export or import key backups, on your account page. See Your account.
Settings that do not exist
In this version you cannot, from Settings or anywhere else in the dashboard:
- delete an organization;
- change an organization's slug;
- end every observe window of the organization at once. End windows per agent (from the banner or the agent's page), or turn observe off. The Cloud API has a route for it (
POST /api/v1/orgs/<org-id>/observe/end-all, for owners, admins, developers and keys withagents:write; see Cloud API), but the dashboard does not use it.