Manage Secrets and Credentials

You can keep provider keys out of your policy config. A provider target refers to its key with secret_key_ref. Use verdictan secret to manage the secret records of your organization, including provider keys. Use verdictan secrets to store a key on your Mac and to check which targets can resolve their keys.

For a first local gateway, an environment variable is sufficient.

Key location	Reference in the policy config	How the gateway gets the key
Provider key saved in the Console	secret_key_ref: { store: "<name>" }	A connected gateway asks the control plane for the provider key of the target's provider. The agent must have access to the key.
macOS Keychain, from verdictan secrets add	secret_key_ref: { keychain: "<name>" }	The gateway reads the Keychain on the same Mac.
Environment variable	secret_key_ref: { env: "<VARIABLE_NAME>" }	The gateway reads its own environment.

For a store reference, the control plane selects the key by provider, not by <name>. When the organization has no provider key for the provider, and the target does not set required: true, the gateway uses the variable VERDICTAN_<name> or <name> from its environment, if one is set. To save a provider key and give agents access to it, see Save a key and grant agent access.

verdictan secret calls the API. verdictan secrets does not.

Before you start

• For verdictan secret: an API credential, from VERDICTAN_API_TOKEN or verdictan auth login. You need the secrets:read permission for list and get, and secrets:write for create, update, and delete.
• For verdictan secrets add: macOS.
• For verdictan secrets status: a policy config file.

verdictan secret

verdictan secret lists, creates, changes, and deletes the secret records of your organization. list and get include the provider keys saved in the Console. The commands do not accept a secret value as a flag. They read it from an environment variable, a macOS Keychain entry, or standard input. They send the value to the API, which stores it encrypted.

create makes records of the kind secret. A gateway does not use these records as provider keys. To add a provider key, use the Console. To replace the value of a provider key, use update.

Usage

verdictan secret list [--json]
verdictan secret get --secret-id <id> [--json]
verdictan secret create --name <name> (--env-var <VAR_NAME> | --keychain <service:account> | --stdin) [OPTIONS]
verdictan secret update --secret-id <id> [--description <text>] [--env-var <VAR_NAME> | --keychain <service:account> | --stdin] [--json]
verdictan secret delete --secret-id <id> --yes [--json]

Options

Flag	Applies to	Description
--secret-id <id>	get, update, delete	Mandatory. The secret ID.
--name <name>	create	Mandatory. The secret name. It must be unique in the organization.
--description <text>	create, update	A description.
--env-var <VAR_NAME>	create, update	Read the value from this environment variable. The name can contain only uppercase letters, digits, and underscores.
--keychain <service:account>	create, update	Read the value from this macOS Keychain entry.
--stdin	create, update	Read the value from standard input. The command removes the final line break.
--kind <kind>	create, list	The API accepts only secret, the default. Other values fail. The API ignores --kind on list.
--yes	delete	Mandatory confirmation.
--json	All	Print the API response as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	All	The CLI config file, API URL, profile (the default is default), and region.

Use only one of --env-var, --keychain, and --stdin. create needs one of them. update needs one of them, or --description, or both.

Save a key in Verdictan

1. Load the value into an environment variable from your secret manager. Then create the record:

   verdictan secret create \
     --name REPORTING_WEBHOOK_TOKEN \
     --env-var REPORTING_WEBHOOK_TOKEN \
     --description "Token for the reporting webhook"

   The command prints created secret <id>.

2. Examine the record:

   verdictan secret get --secret-id "<secret-id>"

   The output has the id, name, source, created_at, and updated_at fields. list prints one line for each record with the ID, name, and source. Neither command returns the value.

Rotate or remove a saved key

1. Find the record. For a provider key, look for "secret_kind": "provider_key" and the provider value:

   verdictan secret list --json

2. Send the new value through standard input:

   printf '%s' "$NEW_VALUE" | verdictan secret update --secret-id "<secret-id>" --stdin

   The command prints updated secret <id>.

3. For a provider key, send a request through a connected gateway to confirm that the provider accepts the new key. Revoke the old key at the provider only after that.

To remove a record:

verdictan secret delete --secret-id "<secret-id>" --yes

The command prints deleted secret <id>. It does not prompt, and the API does not check for references. When you delete a provider key, connected gateways cannot get a key for that provider from the control plane.

verdictan secrets

verdictan secrets works on your workstation only. It does not call the API.

Usage

verdictan secrets add <name> [--keychain]
verdictan secrets status [--config <path>]

Options

Flag	Applies to	Description
<name>	add	Mandatory. The secret name, such as VERDICTAN_OPENAI_API_KEY. It can contain letters, digits, and underscores, and must start with a letter or an underscore.
--keychain	add	Selects the macOS Keychain. This is the only backend, so the flag has no effect.
--config <path>	status	The policy config. The default is policy-config.yaml.

Store a key in the macOS Keychain

1. Store the key:

   verdictan secrets add VERDICTAN_OPENAI_API_KEY

   In a terminal, the command asks for the value and does not show what you type. From a pipe, it reads one line. It prints Secret 'VERDICTAN_OPENAI_API_KEY' stored successfully in keychain.

   The Keychain entry has the service VERDICTAN_OPENAI_API_KEY and the account verdictan.

2. Refer to the entry in the provider target:

   secret_key_ref:
     keychain: VERDICTAN_OPENAI_API_KEY

   A keychain reference without an account uses the account verdictan.

Check which targets can resolve a key

verdictan secrets status --config policy-config.yaml

The output has one row for each provider target:

Provider ID              Secret Ref               Type       Status
------------------------------------------------------------------------
openai-env               VERDICTAN_OPENAI_API_K…  env        ✓ configured
anthropic-store          ANTHROPIC_PRODUCTION_K…  store      ? (store)
openai-keychain          VERDICTAN_OPENAI_API_K…  keychain   ? (keychain unsupported)

Reference type	Status values
env	✓ configured when the variable is set. ✗ missing when it is not set.
keychain	On macOS, ✓ configured or ✗ missing. On other systems, ? (keychain unsupported).
store	Always ? (store). The command does not call the API.
No reference	(inline) and ✓ configured when the target has an inline key or does not need a key. (none) and ✗ missing when the target needs a key.

The command shortens names that are longer than 23 characters. When a row has ✗, it prints one or more provider secrets are missing or unresolved and exits with code 2. A ? status does not change the exit code.

After the keys resolve, run verdictan gateway check --config policy-config.yaml --verbose to check the full config.

Limits and failure behavior

• secrets add stores values in the macOS Keychain only. On other systems, it reads the value and then stops with keychain storage is only available on macOS.
• secret create --keychain and secret update --keychain read the Keychain, so they work on macOS only.
• secret create stores the value, not the variable name. When the variable changes later, run secret update again.
• The API removes spaces and line breaks at the start and end of the value.
• secret create --kind provider_key fails, because the CLI cannot send the provider field that the API needs for this kind. Add provider keys in the Console.
• secrets status checks that a variable or Keychain entry exists. It does not check that the provider accepts the key.

Troubleshooting

Symptom	Cause	Fix
specify exactly one of --env-var, --keychain, or --stdin as the secret source	create has no value source.	Add one source flag.
invalid env var name '<name>': must contain only uppercase ASCII letters, digits, and underscores	The --env-var name has other characters.	Use an uppercase variable name.
env var <name> is not set	The variable is not set in the shell.	Set the variable, or use --stdin.
secret value from stdin must not be empty	Standard input is empty.	Send the value through the pipe.
--keychain value must be in the format 'service:account'	The --keychain value has no colon.	Give the service and the account.
pass --yes to confirm deleting secret <id>	delete has no --yes.	Add --yes.
nothing to update: provide at least one field	update has no description and no value source.	Add --description or a value source.
missing api token (set VERDICTAN_API_TOKEN or run ...)	No API credential.	Set VERDICTAN_API_TOKEN or run verdictan auth login.
command-line token flags have been removed; ...	The command has a token flag.	Remove the flag and use VERDICTAN_API_TOKEN or a profile.
HTTP 409 with secrets.name_conflict	A secret with the name exists.	Use update or a different name.
config file not found: <path>	status cannot find the config.	Give the path with --config.
invalid secret name '<name>': ...	The add name has other characters, or starts with a digit.	Use letters, digits, and underscores.

Next steps

• Environment Variable Use: select between env, keychain, and store references.
• Declarative Config Reference: find the secret_key_ref fields of a provider target.
• verdictan gateway run: start the gateway after the keys resolve.