Secrets And Credentials
Secrets are sensitive values an agent may need to use a service: credentials, API keys, tokens, passwords, or environment-style values.
Do not paste secrets into chat messages, files, or template instructions. Use the platform's secrets flows so the value can be stored and scoped intentionally.
Secret scopes
| Scope | Use it for |
|---|---|
| agent-scoped secret | A value only one agent should use. |
| My secret | A reusable value for the member's own workspace in one Organization. It is not shared with that member's workspace in another Organization. |
| Team secret | A shared value available to agents in one Team. |
| Organization secret | A company-managed value inherited by Organization-governed workflows. |
| System skill profile secret | A value used by an admin-configured system skill profile. |
Available scopes depend on your role and deployment.
HTTP credential destinations
The HTTP and secure API tools use explicit $[secret:key] references in URL paths or query strings, header values, or body values. Bare keys are ordinary text. Legacy <<<key>>> references and missing, pending, or unauthorized credentials reject the request before sending.
Each referenced Credential must permit the literal destination. A restriction such as https://api.example.com permits HTTPS on port 443; add :8443 to permit that exact port instead. A restriction without a scheme defaults to HTTPS. https://*.example.com permits the named domain and its subdomains, with a hostname boundary. Paths and queries are not domain restrictions. Environment Variable secrets are for sandbox execution and cannot be used as HTTP credentials.
References cannot supply a URL's scheme, hostname, or port. A supplied Host header must match the destination. Requests carrying these credentials do not follow redirects, including redirects within the same domain. Verify the endpoint and the result of any prior write before making a new request; do not automatically forward credentials to a redirect target.
Requested secrets
An agent may request a secret when it cannot complete work without one. The request should explain what it needs and why.
Before fulfilling a request:
- Confirm the destination or service.
- Confirm the agent actually needs the value.
- Prefer least-privilege credentials.
- Avoid broad admin tokens when a narrower token works.
- Decide whether the secret should stay agent-scoped or be promoted for reuse.
Manage secrets
Global secrets:
- hosted deployment:
https://your-deployment.example/app/data/secrets
agent-specific secrets:
- hosted deployment:
https://your-deployment.example/app/agents/<agent_id>/secrets/
Safe operating rules
- Rotate credentials if they may have been pasted into chat or files.
- Remove secrets that are no longer needed.
- Use separate credentials per environment when possible.
- Keep production and testing credentials separate.
- Do not share secrets through template instructions.
- Review organization secrets periodically.
If an agent cannot access a service
Check:
- Whether the secret request has been fulfilled.
- Whether the secret is scoped to this agent or organization.
- Whether the credential still works at the provider.
- Whether a connected app or OAuth flow is also required.
- Whether the agent needs a narrower instruction about when to use the secret.