This page covers day-to-day secrets operation: the supported credential surface, required behavior and precedence, activation and recovery signals, and the audit, configure, and apply workflow.

Supported credential surface

Canonical supported and unsupported credentials are listed in SecretRef Credential Surface.

Required behavior and precedence

• Field without a ref: unchanged.
• Field with a ref: required on active surfaces during activation.
• If both plaintext and ref are present, the ref takes precedence on supported precedence paths.
• The redaction sentinel __APUS_REDACTED__ is reserved for internal config redaction/restore and is rejected as literal submitted config data.

Warning and audit signals:

• SECRETS_REF_OVERRIDES_PLAINTEXT (runtime warning)
• REF_SHADOWED (audit finding when SQLite auth-profile credentials take precedence over apus.json refs)
• STORE_PLAINTEXT_RESIDUE (audit finding when a stored name still has an equivalent plaintext config value)
• PLACEHOLDER_VALUE (audit error when a resolved credential or store entry contains a known redaction placeholder; counted as unresolved)

Google Chat serviceAccount accepts inline JSON or a SecretRef. Doctor moves the retired sibling serviceAccountRef into this canonical field when it is unset.

Activation triggers

Secret activation runs on:

• Startup (preflight plus final activation)
• Config reload hot-apply path
• Config reload restart-check path
• Manual reload via secrets.reload
• Gateway config write RPC preflight (config.set / config.apply / config.patch), validating active-surface SecretRefs within the submitted config payload before persisting edits

Activation contract:

• Success swaps the snapshot atomically.
• A strict startup failure aborts Gateway startup.
• During cold startup, a retryable resolution failure for a mapped, isolatable non-Gateway owner may publish the snapshot with that exact owner configured-unavailable. Requests for the owner fail with SECRET_SURFACE_UNAVAILABLE; model-provider owners do not fall back to environment or auth-profile credentials after an explicit ref fails.
• Reload and restart-check isolate eligible mapped owners. Unchanged ref identities with unchanged provider definitions and an unchanged complete non-secret owner contract retain their exact last-known-good values as stale; changed or newly configured unresolved refs publish cold for only that owner. A strict reload failure preserves the previously active snapshot.
• config.set, config.apply, and config.patch accept syntactically valid unresolved refs for isolatable owners and return a redacted degradedSecretOwners report. Gateway ingress auth, structurally invalid config or resolved values, policy violations, and unknown owners still reject before disk mutation.
• Healthy sibling owners resolve and publish normally even when another owner is cold or stale.
• A known redaction placeholder makes its mapped, isolatable owner configured-unavailable without reusing its previous credential, even when another reference for that owner also fails. Gateway token/password auth refuses startup with the affected reference and repair guidance. Doctor can repair store-backed Gateway tokens after a verified backup; other secrets require replacement at their source.
• Providing an explicit per-call channel token to an outbound helper/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit secrets.reload.

Degraded and recovered signals

When reload-time activation fails after a healthy state, Apus enters degraded secrets state, emitting one-shot system events and log codes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Behavior:

• Degraded: healthy owners refresh, stale owners keep last-known-good, and cold owners remain unavailable.
• Recovered: emitted once after the next successful activation. It confirms recovery, including cold owners that had no usable previous credential.
• Repeated failures while already degraded log warnings but do not re-emit the event.
• A strict startup failure never emits a degraded event, because runtime never became active. A successful startup with cold owners logs the owner degradation but does not emit a reloader event.
• Ref-scoped startup and reload failures emit a structured SECRETS_DEGRADED warning for each affected owner. Provider-scoped outages emit one SECRETS_PROVIDER_DEGRADED warning with the provider and complete affected-owner list instead of repeating the provider failure per owner. Warnings include a redacted reason, cold or stale owner state, and the apus secrets reload retry hint. They never include resolved values or SecretRef ids.
• apus doctor lists cold and stale owners with their affected config paths, redacted reason, and retry guidance.
• Retired auth-profile files that require migration report auth profile migration required in Gateway warnings and Doctor, with apus doctor --fix as the repair command. Doctor owns the verified import and archival; reloading secrets does not migrate these files.
• Channel health and status keep cold accounts visible as configured but unavailable, alongside healthy accounts. Read-only inspection does not resolve inactive credentials or check cold accounts. /healthz still reports Gateway liveness; /readyz may report the affected channel as failing until it recovers. Restore the secret, then run apus secrets reload.

Command-path resolution

Command paths can opt into supported SecretRef resolution via a gateway snapshot RPC. Two broad behaviors apply:

For example `apus memory` remote-memory paths and `apus qr --remote` when it needs remote shared-secret refs. They read from the active snapshot and fail fast when a required SecretRef is unavailable.

For example `apus status`, `apus status --all`, `apus channels status`, `apus channels resolve`, `apus security audit`, and read-only doctor/config repair flows. They also prefer the active snapshot, but degrade instead of aborting when a targeted SecretRef is unavailable.

Read-only behavior:

- When the gateway is running, these commands read from the active snapshot first.
- If gateway resolution is incomplete or the gateway is unavailable, they attempt a targeted local fallback for that command surface.
- If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and an explicit diagnostic that the ref is configured but unavailable in this command path.
- This degraded behavior is command-local only; it does not weaken runtime startup, reload, or send/auth paths.

Agent turns using the matching prepared Gateway snapshot do not re-resolve every model and tool credential at turn startup. A configured-unavailable provider therefore does not block a turn using a healthy provider. Selecting the unavailable provider still fails closed before environment or auth-profile fallback, and explicitly targeted channel/account credentials remain strict.

Standalone agent commands without config-ref preparation and calls with a different config retain strict command-scoped resolution. A local non-delivery agent command does not resolve unrelated channel or Gateway credentials.

Other notes:

• Snapshot refresh after backend secret rotation is handled by apus secrets reload.
• Gateway RPC method used by these command paths: secrets.resolve.

Audit and configure workflow

Default operator flow:

```bash
apus secrets audit --check
```

```bash
apus secrets configure --apply
```

```bash
apus secrets audit --check
```

Do not treat the migration as complete until the re-audit is clean. If the audit still reports plaintext values at rest, the agent-access risk remains even when runtime APIs return redacted values.

If you save a plan instead of applying during configure, apply that saved plan with apus secrets apply --from <plan-path> before the re-audit.

Findings include:

- Plaintext values at rest (`apus.json`, SQLite auth-profile rows, `.env`, and generated `agents/*/agent/models.json`).
- Plaintext sensitive provider header residues in generated `models.json` entries.
- Unresolved refs.
- Precedence shadowing (SQLite auth profiles taking priority over `apus.json` refs).
- Store residue (a stored name still has an equivalent plaintext value in config).

Initially missing generated `models.json` files are skipped. When reading an existing file, audit enforces a 5 MiB limit and reports leaf symlinks, non-regular files, and read or parse failures as `REF_UNRESOLVED`. Parse diagnostics identify the file without echoing its contents.

Exec note: by default, audit skips exec SecretRef resolvability checks to avoid command side effects. Use `apus secrets audit --allow-exec` to execute exec providers during audit.

Header residue note: sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).

Interactive helper that:

- Configures `secrets.providers` first (`env`/`file`/`exec`/`store`, add/edit/remove).
- Lets you select supported secret-bearing fields in `apus.json` plus the SQLite auth-profile store for one agent scope.
- Can create a new auth-profile mapping directly in the target picker.
- Captures SecretRef details (`source`, `provider`, `id`).
- Runs preflight resolution and can apply immediately.

Exec note: preflight skips exec SecretRef checks unless `--allow-exec` is set. If you apply directly from `configure --apply` and the plan includes exec refs/providers, keep `--allow-exec` set for the apply step too.

Helpful modes:

- `apus secrets configure --providers-only`
- `apus secrets configure --skip-provider-setup`
- `apus secrets configure --agent <id>`

`configure` apply defaults:

- Scrub matching static credentials from SQLite auth-profile rows for targeted providers.
- Leave retired `auth.json` untouched; run `apus doctor --fix` to migrate and archive it.
- Scrub matching known secret lines from the effective state and active-config `.env` files (deduplicated when both paths match).

Apply a saved plan:

```bash
apus secrets apply --from /tmp/apus-secrets-plan.json
apus secrets apply --from /tmp/apus-secrets-plan.json --allow-exec
apus secrets apply --from /tmp/apus-secrets-plan.json --dry-run
apus secrets apply --from /tmp/apus-secrets-plan.json --dry-run --allow-exec
```

Exec note: dry-run skips exec checks unless `--allow-exec` is set; write mode rejects plans containing exec SecretRefs/providers unless `--allow-exec` is set.

For strict target/path contract details and exact rejection rules, see [Secrets Apply Plan Contract](/gateway/secrets-plan-contract).

One-way safety policy

Safety model:

• Preflight must succeed before write mode.
• Runtime activation is validated before commit.
• Apply updates files using atomic file replacement and best-effort restore on failure.

Legacy auth compatibility notes

For static credentials, runtime no longer depends on plaintext legacy auth storage.

• Runtime credential source is the resolved in-memory snapshot.
• Legacy static api_key entries are scrubbed when discovered.
• OAuth-related compatibility behavior remains separate.

Control UI

Open Settings → Secrets to list, add, edit, bulk-import, or soft-delete team-scoped entries. Choose Protected secret for write-only values used by SecretRefs or destination-bound Gateway egress. Choose Agent-readable environment only when Gateway-hosted agent commands must receive plaintext and the agent may print, transmit, or persist it. Bulk Add accepts dotenv NAME=VALUE assignments, including quoted multiline values. Protect credential-like names automatically defaults credential-shaped names to protected mode.

This store page manages values only. Configure the corresponding store SecretRef on a supported field through its settings form or the raw editor. Identity-scoped entries are reserved for a later release and are not exposed by this page.