Tool Credentials & Permissions

Envelope separates the team definition (what the agents do) from the credentials (what they're allowed to access). This guide explains the model and how to wire credentials at deploy time.

The separation principle

An .envelope.json spec is designed to be committed to Git without embedding any secrets. It declares what credentials a team needs — not their values:

{
  "name": "Support Triage",
  "agents": [...],
  "requiredSecrets": ["ZENDESK_API_KEY", "SLACK_BOT_TOKEN"],
  "requiredVariables": ["SUPPORT_QUEUE_EMAIL"]
}

| Field | Contains | Example | |-------|---------|---------| | requiredSecrets | Names of credentials that must be provided | "ZENDESK_API_KEY" | | requiredVariables | Names of non-secret config values | "SUPPORT_QUEUE_EMAIL" | | Agent capabilities | Tool categories the agent uses | ["zendesk", "slack"] |

The spec tells you what is needed. How you provide it is a deployment-time decision.

Capabilities vs secrets

Capabilities (per agent) signal which tool categories an agent uses: slack, zendesk, github, gmail, etc. These are qualitative — they help you understand what the agent does and what permission scopes it will need.

Required secrets (top-level) are the exact environment variable names that must be populated before a run can start. An agent with "capabilities": ["zendesk"] will almost certainly have "ZENDESK_API_KEY" in requiredSecrets.

Providing credentials

Option 1 — Envelope org vault (recommended)

Store credentials in your Envelope org vault once. They're applied automatically whenever a matching team is installed.

Go to Workspace Settings → Credentials
Add each secret by name (matching the name in requiredSecrets)
Install the team — credentials are injected at runtime, never stored in the spec

Option 2 — Pass at install time (API)

When installing via the API, provide credentials directly:

curl -X POST https://openenvelope.org/api/installs/{installId}/secrets \
  -H "Authorization: Bearer $ENVELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ZENDESK_API_KEY": "zdg_...",
    "SLACK_BOT_TOKEN": "xoxb-...",
    "SUPPORT_QUEUE_EMAIL": "[email protected]"
  }'

Option 3 — Your own secrets manager

If you're running agents in your own infrastructure (not via Envelope's MCP or API), inject secrets from your secrets manager (AWS Secrets Manager, Vault, 1Password Secrets Automation, etc.) as environment variables before the agents run. The variable names in requiredSecrets are the keys to populate.

Scoping credentials to agents

Each agent only uses the credentials relevant to its capabilities. You don't need to audit which agent needs what — the spec already encodes this:

{
  "key": "triage-agent",
  "capabilities": ["zendesk"],
  "reportsTo": "supervisor-agent"
},
{
  "key": "notifier-agent",
  "capabilities": ["slack"]
}

The triage agent only ever accesses Zendesk; the notifier only accesses Slack. This is enforced at the prompt level — each agent's system prompt is scoped to its role.

What stays out of the spec

Never put credential values in the spec file:

// DO NOT DO THIS
{
  "requiredSecrets": {
    "ZENDESK_API_KEY": "zdg_live_abc123"  // wrong — this is a value
  }
}

The correct form is always a list of names:

{
  "requiredSecrets": ["ZENDESK_API_KEY"]
}

The spec is safe to store in Git, share with colleagues, and export to IT teams — precisely because it contains no secrets.