Credential Management

Open the agent detail page and click the Credentials tab. The checklist answers three questions per credential:

Fill in the values you have and submit — the checklist writes through the same owner-gated injection path as everything else on this tab.

The checklist renders even when the agent is stopped: you can see what an agent will need before starting it, with the live-status column honestly reported as unavailable. If the status probe fails, you are told so — a failed probe is never shown as “nothing configured”.

Reading this checklist is owner-only and human-only: it is an operator surface, and agent-scoped API keys are rejected.

credentials:
  env_file:
    - OPENAI_API_KEY
  mcp_servers:
    slack:
      env_vars:
        - SLACK_BOT_TOKEN

credential_setup:
  - name: OPENAI_API_KEY
    title: OpenAI API key
    description: Lets the agent call OpenAI models directly.
    required: true
    secret: true
    setup_url: https://platform.openai.com/api-keys

credentials: is names-only and will never accept per-variable objects — that is what keeps older Trinity versions able to read a newer template. All the human-facing detail lives in credential_setup:, where each entry may carry title, description, required, secret, format, setup_url, and a non-secret default.

Two rules make the pair safe:

secret defaults to true and setup_url must be https with no embedded userinfo, so a credential is masked until an author says otherwise and a setup link cannot impersonate a vendor domain.

The full contract is published at docs/schemas/trinity-agent-credentials.schema.json.

Add credentials using one of four methods on the Credentials tab:

Hot-reload — Paste or edit credentials on a running agent. The .env file is updated and .mcp.json is regenerated immediately. No restart needed.

The credential file pattern inside each agent:

.env                    # Source of truth (KEY=VALUE)
.mcp.json.template      # Template with ${VAR} placeholders
.mcp.json               # Generated at runtime from template + .env

Injection accepts a curated set of credential file types, not just .env. Anything outside the allow-list — and anything on the deny-list — is rejected with a 400.

Always blocked (deny takes precedence): anything executed or sourced at startup — shell startup files (.bashrc, .profile, .zshrc, …), agent instruction files (CLAUDE.md, AGENTS.md, .claude/**), .mcp.json.template, .ssh/authorized_keys / .ssh/config, .git/** and .gitconfig, anything under bin/, plus absolute paths and .. traversal. .mcp.json content is structurally validated before it is written.

Binary credentials (certificates, keystores, service-account bundles) round-trip as base64 via the files_b64 field on the inject endpoint.

Export creates an encrypted .credentials.enc file for backup. It captures the full injected credential set — every allow-listed credential file present in the agent (discovered live), text and binary alike — not just .env and .mcp.json. Import decrypts and injects credentials from an encrypted file; the archive is re-validated against the same path policy on the way in. Auto-import on startup is not currently available. The agent's startup script still tries to import a .credentials.enc it finds without a .env, but the internal route it calls no longer exists, so the attempt is logged as “Could not auto-import credentials” and the agent starts without them. Use Import from the Credentials tab (or the import endpoint) instead.

Credential values are never logged. All operations use structured logging with values masked.

The platform encryption key (CREDENTIAL_ENCRYPTION_KEY) can be rotated online, with zero downtime and no data loss:

The sweep re-encrypts every database-persisted token (subscriptions, channel bot tokens, GitHub PATs, payment credentials). Per-agent .credentials.enc files re-encrypt onto the new key on their next credential operation; they keep opening via the secondary key until then. Full runbook: docs/migrations/CREDENTIAL_KEY_ROTATION.md.

The vault holds named credentials once, encrypted (AES-256-GCM), and grants them per agent. An agent asks for a granted value by name at runtime; nothing is written into its .env.

As an admin, open Settings → Vault (the tab appears only on an instance where the vault is enabled). Click Add a credential, then open its Grants and Grant it to the agents that may read it; Revoke takes a grant back and Delete removes the entry. Values are never shown again after you save them. After rotating the platform encryption key, the Key-rotation maintenance disclosure re-encrypts every entry; entries encrypted under a key the instance no longer has are counted so you can restore the previous key as CREDENTIAL_ENCRYPTION_KEY_SECONDARYand re-encrypt. Managing entries and grants requires an administrator signed in interactively — an API key of any scope is refused.

From inside an agent, two MCP tools exist in every build:

Where the vault is not available — an instance without the entitlement, or a call made without an agent-scoped key — the tools do not error. list_available_credentials returns enabled: false with a reason, and fetch_credential returns success: false with a flag that distinguishes not granted, needs an agent key, and not available on this platform.

What happens to the value. The credential reaches the agent live, as a plain tool result, because that is what the agent needs to do its work. Trinity then scrubs that value out of everything it persists from the turn — the transcript, the execution log, the response and error columns, notifications, channel completion reports, and the cached response replayed to duplicate requests — replacing every occurrence (raw, JSON-escaped, and base64) with ***REDACTED***. The scrub runs alongside the existing pattern-based sanitizer, not instead of it. Two honest limits: it covers what the platform stores, not the agent's own in-container session files, and it applies to values fetched within the last 24 hours.

The credentials the platform itself holds — the Anthropic API key, platform GitHub PAT, Resend email key and Gemini key (Settings → Integrations → API Keys; see Platform Keys), and the Slack app token, client secret, and signing secret (Settings → Integrations → Slack Integration) — are stored AES-256-GCM encrypted at rest, never in cleartext. An install upgraded from an older release re-encrypts a leftover cleartext row the first time it is read and deletes the cleartext copy, so a restored old backup or a direct database write cannot leave a plaintext value behind for long.

The generic settings route refuses to store a secret in the clear: PUT /api/settings/{key} for any of those keys, or for any credential-shaped key (*_api_key, *_token, *_secret, *_pat, *_password, *_credentials), answers 422 and names the dedicated route to use. The Slack client IDis a reviewed exemption — it is a public OAuth identifier that appears verbatim in the authorize URL.

Encryption protects the database going forward only. Backups taken before the upgrade still hold the plaintext values, so an upgrading install should rotate those tokens — runbook: SECRET_SETTINGS_ENCRYPTION_2026-08.md.

Trinity exposes a small OAuth2 helper API for four providers — Google, Slack, GitHub, and Notion — that builds a provider authorization URL from client credentials configured on the backend. It does not complete the OAuth exchange for you: Trinity currently ships no handler for the callback and no OAuth button on an agent's Credentials tab. The practical way to give an agent a provider token today is to obtain it yourself and add it through the Credentials tab as KEY=VALUE in .env, where the agent's .mcp.json.template picks it up through ${VAR} placeholders.

Platform-level Slack installation is a separate, complete OAuth flow (Install to Workspace in the Slack Integration settings section). Full details, endpoints, and scopes: OAuth Credentials.

Share Claude Max/Pro subscription tokens across multiple agents, with automatic assignment, live usage and headroom readings, early warnings before a weekly limit, and automatic switching when a subscription is rate-limited — so a turn completes on another subscription instead of failing.

Usage and headroom readings, weekly-limit alerts, the full switching sequence, the settings reference, and the complete API are on Subscription Credentials.