Skip to main content
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

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.
Do not paste credentials into Chat, task descriptions, or files. Save them as secrets and tell the agent the secret name.
Related: Git provider tokens, Members and permissions.