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

# Secrets and variables

> Store API keys and tokens so agents can use them by name without seeing or repeating the value.

Secrets let an agent call an external service with your API key or token without the value appearing in Chat, task files, or the model's context. The agent refers to a secret by its name, such as `GITHUB_TOKEN`; AgentDesk attaches the value to the outgoing request outside the agent sandbox.

## Secret or variable

| Type | Use it for | After saving |
| - | - | - |
| **Secret** | Passwords, API keys, and tokens. | The value cannot be viewed again. Agents use it only through approved requests. |
| **Variable** | Non-sensitive settings, such as a region or account ID. | Agents and members with access can read the value. |

Names use capital letters, digits, and `_`, start with a letter, and have at most 64 characters.

## Where secrets live

* **Project secrets**: open a Project and choose **Secrets & Variables**, or use **Secrets…** in the project menu in the Chat sidebar. Agents working in that project can use them.
* **Workspace secrets**: open **Settings > Secrets**. A workspace secret is a shared credential; link it to each project that may use it with **Link to projects…**. **All secrets by project** shows what each project can use.

When a project secret and a linked workspace secret have the same name, the project secret takes precedence; the workspace entry shows **Overridden by Project**.

Only a workspace Owner or Manager can add, rotate, or revoke secrets. Other members see secret metadata (name, type, status, last use), never secret values.

## Add a secret

1. Choose **Add secret** (or **Add workspace secret**).
2. Choose **Secret** or **Variable**, enter the name and value. Use **Add another** to add several at once, or **Import .env** to paste `KEY=value` lines.
3. Optional: open **Advanced options**:
   * **Agents allowed to use it**: all agents in the project (or in linked projects), or only selected agents.
   * **Allowed websites (hosts)**: the value is only sent to these hosts. A request to any other host needs your approval first.
   * **How the value is sent**: Bearer token, custom header, Basic auth, query parameter, or a `{{secret:NAME}}` placeholder. The service is usually recognized from the key prefix.
   * **Read requests (GET)** and **Write requests (POST, PUT, DELETE)**: **Allow automatically**, **Ask the first time**, **Ask every time**, or **Deny**.
   * **Expires on** and **Note**, for example where to rotate the key.
4. Save.

## Manage secrets

From the row actions:

* **Rotate value** replaces the value immediately. Agents keep using the same name.
* **Edit policy** changes allowed agents, hosts, and approval rules.
* **Revoke** stops all future use. Turn on **Show revoked** to see revoked entries.
* The audit drawer lists every change and every use, including approvals and denied requests.

## Secrets in Chat

**Approval cards.** When an agent wants to use a secret on a new host or with a write method that requires approval, Chat shows **Secret approval needed**. Choose **Allow once**, **Always allow**, or **Deny**, then ask the agent to retry.

**Missing secrets.** When an agent needs a secret that does not exist yet, Chat shows a card where you enter the value. It goes straight to the vault and never into the conversation. Ask the agent to retry after saving.

**Pasted secrets.** If you paste or try to send something that looks like a key or token, the composer warns you:

* **Save as secret** stores it in the vault and keeps only the secret name in your message.
* **Remove** deletes it from the draft.
* **Send anyway** asks for confirmation, because the value will be visible to the model and kept in the conversation history.

<Warning>
  Do not paste credentials into Chat, task descriptions, or files. Save them as secrets and tell the agent the secret name.
</Warning>

Related: [Git provider tokens](/user-guide/git-provider-tokens), [Members and permissions](/user-guide/members-permissions).


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