> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# secrets

> Contract, placement, related fields and source examples for this Nika YAML field.

[Language reference](/reference/language/overview) / `secrets`

## Meaning and placement

### document

Vault-backed masked references · `${{ secrets.X }}` · never inline literals.

| Property             | Declaration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Requirement          | Optional in this object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Schema location      | `/properties/secrets`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| type                 | "object"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| additionalProperties | \{"type": "object", "additionalProperties": false, "required": \["source"], "properties": \{"source": \{"enum": \["vault", "env", "file"], "description": "Where the secret lives · never an inline value (spec/01-envelope.md §secrets)."}, "key": \{"type": "string", "description": "Store key (vault) or OS env var name (env)."}, "path": \{"type": "string", "description": "File path · file source only · contents read at resolve time · masked."}, "egress": \{"type": "array", "description": "Sanctioned destinations for this secret · declassification (spec/01-envelope.md §egress) · absent/empty = default-deny (every exec:/invoke: reach is a leak).", "items": \{"type": "object", "additionalProperties": false, "required": \["to"], "properties": \{"to": \{"type": "string", "description": "The sanctioned sink · a tool id (`nika:fetch` · `nika:notify` · `mcp:<server>/<tool>`), `exec`, a provider-egress sink `infer` / `agent` (a secret in an infer/agent prompt), or `outputs` (the workflow boundary — a return value derived from the secret's response) · SPECIFIC (no cross-tool laundering)."}, "host": \{"type": "string", "description": "Static-literal destination host · sanctions only when the sink's destination arg is exactly this host (a templated host stays the runtime check). Mutually exclusive with host\_from\_self."}, "host\_from\_self": \{"type": "boolean", "description": "The secret value IS the destination URL (host unknown statically) · sanctions only the direct-secret-URL shape with the non-occlusion guard. Mutually exclusive with host."}}, "not": \{"required": \["host", "host\_from\_self"]}}}}, "allOf": \[\{"if": \{"properties": \{"source": \{"const": "file"}}}, "then": \{"required": \["path"], "not": \{"required": \["key"]}}, "else": \{"required": \["key"], "not": \{"required": \["path"]}}}], "description": "A secret is a reference to a store · discriminated by source · vault/env require key · file requires path · optional egress: sanctioned-destination list (spec/01-envelope.md)."} |

**In the same object:** [const](/reference/language/words/const) · [inputs](/reference/language/words/inputs) · [model](/reference/language/words/model) · [nika](/reference/language/words/nika) · [outputs](/reference/language/words/outputs) · [permits](/reference/language/words/permits) · [run](/reference/language/words/run) · [tasks](/reference/language/words/tasks)

[Schema source (use the pointer above)](https://github.com/supernovae-st/nika-spec/blob/c5ebbb7b862b68bc6cf7235efba61173b844afc6/schemas/workflow.schema.json)

## In a source template

Excerpt from `templates/api-upload-and-create.nika.yaml`, source lines 40–49. This is a fragment, not a runnable workflow.

```yaml illustration theme={"system"}
  api_base: "https://api.example.com"     # SLOT: the product API base
  asset_path: "./out/assets/asset-1.png"  # SLOT: the file to upload

secrets:
  API_KEY:
    source: env
    key: EXAMPLE_API_KEY            # SLOT: the OS env var holding the key
    egress:
      - to: "nika:fetch"            # the send · default-deny otherwise
      - to: "outputs"               # the return value derives from the authed response
```

### Templates containing this field

| Template                                    | Source                                                                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `templates/api-upload-and-create.nika.yaml` | [Line 43](https://github.com/supernovae-st/nika-spec/blob/c5ebbb7b862b68bc6cf7235efba61173b844afc6/templates/api-upload-and-create.nika.yaml#L43) |
| `templates/gate-and-act.nika.yaml`          | [Line 42](https://github.com/supernovae-st/nika-spec/blob/c5ebbb7b862b68bc6cf7235efba61173b844afc6/templates/gate-and-act.nika.yaml#L42)          |
| `templates/human-gated-ship.nika.yaml`      | [Line 76](https://github.com/supernovae-st/nika-spec/blob/c5ebbb7b862b68bc6cf7235efba61173b844afc6/templates/human-gated-ship.nika.yaml#L76)      |

These are literal key occurrences in the source files, not an execution or conformance claim. [How to instantiate a template](/guides/templates).

## Contract and implementation

This page projects the named specification revision. Check [released engine status](/reference/status) and [the validation workflow](/guides/agent-authoring) before running a file. An optional field is not evidence that every engine supports every value.

Canonical identity: `language:word:secrets`. Spec revision: [`c5ebbb7b862b`](https://github.com/supernovae-st/nika-spec/tree/c5ebbb7b862b68bc6cf7235efba61173b844afc6).

[How documentation stays connected](/reference/knowledge-system).