Secret

A Secret is a value stored once against a workspace and referenced by name from an agent workflow step, as ${{secrets.KEY}}.

It exists so a workflow can authenticate against your systems without the credential ever appearing in an agent prompt, in an agent's answer, or in the stored record of the request that used it.

Purpose

• Keep credentials out of the model's context: the agent writes the reference, never the value.
• Rotate a credential in one place, with no change to any agent.
• Keep the value out of everything we persist — the request stored on each workflow step is written with every secret value replaced by [REDACTED].

The value is write-only

No endpoint, on any surface, ever returns a secret's value. Not the API, not the MCP tools, not the Kobana back office. It is stored encrypted (AES-256-GCM, bound to the row) and read only by the workflow executor at the moment it builds an outbound request.

If you lose the value, replace it — there is no way to read it back.

Schema

Field	Type	Description
id	UUID	Internal id.
workspace_id	UUID	Owning workspace.
key	string	The identifier a workflow writes inside ${{secrets.KEY}}. Matches ^[A-Z][A-Z0-9_]{0,62}$ — uppercase letters, digits and underscores, starting with a letter.
notes	string | null	Free-text reminder of what the value is for.
last_used_at	datetime | null	Last time a workflow step actually interpolated this secret. null until it is first used.
created_at / updated_at	datetime

value is accepted on write and never returned on read.

Naming

The grammar is narrow on purpose: ${{secrets.A.B}} has no meaning, so a key containing a dot would be unreferenceable. Stick to FINANCE_TOKEN, ERP_BASIC_AUTH, NFE_API_KEY.

Endpoints

Method	Path	Notes
GET	/v1/secrets	List. Keyset-paginated, filterable by key.
POST	/v1/secrets	Create. A duplicate key in the workspace is 409 conflict.
PUT	/v1/secrets	Upsert matched by key — the rotation path, no id lookup needed.
GET	/v1/secrets/{id}	Read one (without the value).
PATCH	/v1/secrets/{id}	Replace value and/or notes. key is immutable.
DELETE	/v1/secrets/{id}	Soft-delete.

Scopes: inbox/secrets to read, plus the global write verb (or inbox/secrets:write) to mutate.

Why key cannot be renamed

Every workflow references the key by name. A rename would keep returning 200 while silently breaking each step that used the old name at its next run. Delete the secret and create the new one instead, then update the agent prompt in the same change.

Deleting

Deletion is soft, like every other resource. From the next run on, a step referencing the key fails with secret \KEY` is not defined in this workspace**before** any request is sent — that step fails there rather than calling your system unauthenticated, and steps that reference it areskipped`.

Example

{
  "id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "key": "FINANCE_TOKEN",
  "notes": "ERP service account — rotates every 90 days",
  "last_used_at": "2026-09-08T14:22:03.118Z",
  "created_at": "2026-06-01T09:14:00.000Z",
  "updated_at": "2026-09-01T09:14:00.000Z"
}