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

# Secrets

> Give an agent API keys and passwords without putting them in its bundle.

Secrets — a CRM API key, a database password — never go into your bundle or `Dockerfile`. You declare their **names** in `agentos.yaml`, an environment admin enters the **values** in the panel, and your code receives them on each invocation in `context.secrets`.

**1. Declare the names**

```yaml agentos.yaml theme={null}
secrets: [CRM_API_KEY, ERP_PASSWORD]
```

Names match `[A-Z][A-Z0-9_]*` and are at most 128 characters.

**2. Set the values**

An environment admin opens the agent's **Secrets** tab and enters each value. A value is never shown again after it is saved. Members of the environment see the names, never the values.

If you deploy a version that declares a name without a value, the deploy warns you: in its log, with a **MISSING SECRETS** badge on the Deploy and Secrets tabs, and in `warnings` on the deploy (`GET /v0/deploys/{id}`).

**3. Read them in your code**

```python Plain HTTP theme={null}
crm_key = body["context"]["secrets"]["CRM_API_KEY"]
```

```python Python SDK theme={null}
crm_key = inv.secrets["CRM_API_KEY"]
```

```ts TypeScript SDK theme={null}
const crmKey = inv.secrets.CRM_API_KEY;
```

`context.secrets` holds the names this version declares that have a value.

## How values are handled

* Values are stored encrypted, decrypted only to build the invoke request, and never written to events, logs or webhooks.
* Secrets are not part of a version. A new value applies from the next invocation on, the resume of a held run included; no redeploy needed.
* The build never gets secrets. Fetch what needs credentials at run time, not in your `Dockerfile`.

## Masking

If your agent echoes a secret of 8 or more characters into its output, its error message, an [event](https://docs.upsonic.ai/agentos/build/files-and-events.md) or an [ask](https://docs.upsonic.ai/agentos/build/human-approvals.md) (intent, details, item titles and data), AgentOS stores it as `***`.

This is a safety net, not a guarantee: an encoded or split value isn't recognised, and a value rotated in the middle of an invocation may stay unmasked in that invocation's later events.

> [!WARNING]
>
> Some things are **not** scrubbed. Keep secrets out of them:
>
> * [state](https://docs.upsonic.ai/agentos/build/state-and-sessions.md) values;
> * the input of [child runs](https://docs.upsonic.ai/agentos/build/child-runs.md) your agent starts;
> * a [streamed answer](https://docs.upsonic.ai/agentos/build/streaming.md), which reaches the caller as written;
> * your own logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.