Skip to main content

​
Manage secrets

​
What this does

A workspace secret stores one JSON object for fleet tools. The client never reads the stored value back. The credential firewall adds values to approved outbound calls. The fleet sees the response, not the secret value.

​
Before you begin

Select the workspace that should own the secret. Prepare a valid, non-empty JSON object.

​
Steps

  1. Create a secret with an obviously fake value.
    Replace the fake value through a secret manager. Avoid putting real values in shell history.
  2. Confirm that the secret exists.
  3. List secret names.

​
Replace a value

Update replaces the stored body in one call. The name stays claimed for the whole call, so fleets that require it keep running.
Replacement is total. Send the whole object you want stored — a field you omit is absent from the secret afterwards. This is deliberate: a stored secret is never readable, so a partial change could not be checked by the caller. Pipe the object on stdin with --data=@- to keep values out of shell history. The dashboard’s Edit dialog performs the same replacement through PUT /v1/workspaces/{workspace_id}/secrets/{secret_name}. A name the workspace does not hold returns UZ-VAULT-003 and creates nothing. Claiming a name is create’s job alone.

​
Verify it works

Install a fleet that declares the secret name. Installation fails with UZ-BUNDLE-003 when a required name is missing. The list and show commands return metadata only. Neither command returns secret fields or values.

​
Common problems

UZ-VAULT-001 means the data is empty or is not a JSON object. Send an object with at least one field. UZ-VAULT-002 means the stored object exceeds 4 KiB. Remove unused fields or shorten values. UZ-VAULT-003 on update means the workspace holds no secret by that name. Create it instead. UZ-VAULT-005 means the workspace already holds that name. Creating a secret claims a name that is free, so nothing is written and the command exits 0. Replace the value with agentsfleet secret update.

​
Remove or undo

Deleting a secret removes the value immediately. Fleets that require the name will fail until you create it again.
Deletion is idempotent. Recreate the same name to restore access with a new value. To replace a value, prefer agentsfleet secret update — deleting first leaves the name absent between the two calls, and any fleet that requires it fails during that gap.