Credentials

The credential.* family (6 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Listcredential.list

Inventory credentials in the workspace (optionally for one connection). NEVER returns the secret - only the masked hint + metadata (INV-7, secret-never-returned). RLS-scoped + explicit workspace predicate.

Input { connectionId? } (fields ending in ? are optional)

Call POST /v/credential.list with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool credential.list.

Revokecredential.revoke

Terminally disable a credential (-> REVOKED, catalogue L216). The ciphertext is RETAINED (for audit/forensics - never returned), the status flips terminal. An already-REVOKED one is an idempotent no-op success. RLS-scoped + explicit workspace predicate.

Input { id } (fields ending in ? are optional)

Call POST /v/credential.revoke with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool credential.revoke.

Rotatecredential.rotate

Replace a credential’s secret IN PLACE (catalogue L215) - re-encrypt the new plaintext (INV-7), re-mask, and RESET verified_at (the rotated secret is unverified until a new credential.verify). A REVOKED credential cannot be rotated (terminal). The plaintext is never logged or returned. RLS-scoped + explicit workspace predicate.

Input { id, secret } (fields ending in ? are optional)

Call POST /v/credential.rotate with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Setcredential.set

Store a connector secret, AES-256-GCM-encrypted at rest (INV-7). The plaintext is encrypted-before-write, the masked hint is computed from the plaintext FIRST, and the plaintext is then dropped - it is NEVER logged, NEVER stored in a column, NEVER returned. A duplicate label on the connection is a friendly Conflict. Size-bound (anti blob-stuff). The connection must exist in this workspace (fail-closed).

Input { connectionId, label, secret } (fields ending in ? are optional)

Call POST /v/credential.set with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool credential.set.

Set Capcredential.setCap

Set the PER-CREDENTIAL spend cap (catalogue L218) - DISTINCT from the org budget.set: a cap on ONE credential, config, MOVES NO MONEY (INV-12 enforces the spend elsewhere). Integer minor-units (C14, no float) + an ISO-4217 currency. A null spendCapMinor CLEARS the cap (uncapped). RLS-scoped + explicit workspace predicate.

Input { id, spendCapMinor?, currency? } (fields ending in ? are optional)

Call POST /v/credential.setCap with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool credential.setCap.

Verifycredential.verify

Dry-run a stored credential: DECRYPT it (proving the at-rest secret is intact, INV-7) and test reachability - the reachability test is STUBBED this beat (no off-box call). On success sets verified_at (catalogue L214). The decrypted plaintext is used in-process only, never returned. RLS-scoped + explicit workspace predicate.

Input { id } (fields ending in ? are optional)

Call POST /v/credential.verify with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool credential.verify.