API

Secrets

Secrets let you register sensitive values, rotate them into new immutable versions, and read back metadata for audits. Plaintext values are accepted on create and update; they are never returned by any read.

This page is the narrative. For exact request and response shapes, the canonical source is the interactive reference's secrets tag.

Mental model

A secret is a named slot. A secret version is one frozen set of values in that slot. Rotating means writing a new version; the old version stays in history with its lifecycle state so you can audit when it was active and when it was retired.

Each version reports:

state: ENABLED (the current value), DISABLED (intentionally not in use), or DESTROYED (purged).
A SHA-256 of the canonical plaintext, for change detection without exposing the value.

When to use a secret

Reach for a secret when:

A value is genuinely sensitive (API keys, signing secrets, database passwords).
The value belongs to your code, not to a provider Mobius integrates with. For known providers (Slack, GitHub, Linear, ...), use an integration; the connect flow is better than rolling your own.
You want a rotation audit (when did this last change? mobius secrets list-versions answers it).

Don't put secrets in loop inputs or step with blocks. Those land in run history, the event log, and audit records.

Typical flow from the CLI

# Register a secret and its first version
mobius secrets create \
  --name openai \
  --description "OpenAI key used by the summarizer." \
  --values '{"api_key":"sk-..."}'
 
# Read metadata (no plaintext, ever)
mobius secrets get openai
mobius secrets list
 
# Rotate: a new ENABLED version, old one moves to DISABLED
mobius secrets update openai --values '{"api_key":"sk-new-..."}'
 
# Audit history
mobius secrets list-versions openai
mobius secrets get-version openai 3

For non-trivial payloads, prefer file input over inline JSON so secrets don't end up in your shell history:

mobius secrets update openai --file new-creds.json --var ENV=prod
rm new-creds.json

Referencing a secret from a loop

Actions resolve secrets by name at execution time. You reference the secret in the action's parameters; Mobius substitutes the value when the action runs. The reference syntax depends on the action; the generic shape looks like ${secret:openai.api_key}. See the action's own documentation in mobius catalog get-action or in the interactive reference for what it expects.

Common errors

Code	HTTP	Cause	Fix
`Bad Request`	400	Body fails schema validation, or `values` is empty.	Send a non-empty `values` object whose values are strings.
`Unauthorized`	401	Missing or invalid credentials.	Attach a valid API key for the project.
`Not Found`	404	Project, secret, or version is unknown or not visible.	Confirm the project handle, secret name or ID, and version.
`Conflict`	409	Secret name already exists on create or update.	Choose a different name, or update the existing secret.

Integrations hold credentials for known providers; integrations and secrets are complementary.
API keys for the auth surface used to read and rotate.
Interactive reference: secrets for every parameter and schema.