Guides/Credential Management

Credential Management

Add, edit, and hot-reload credentials on agents without restarting them. Includes direct file injection, encrypted storage, OAuth flows, and subscription token management.

Overview

Trinity uses a direct file injection system. Credentials are written as .env (KEY=VALUE) and .mcp.json (generated from template) directly to the agent container.

Credential requirements are extracted from .mcp.json.template. The UI shows each credential as configured (green) or missing (red). Credentials can be exported to encrypted .credentials.enc files (AES-256-GCM) for backup and import.

Injecting Credentials

Open the agent detail page and click the Credentials tab.

View required credentials extracted from the agent's .mcp.json.template. Status shows configured or missing per credential.

Add credentials using one of three methods:

• Manual entry — Name, value, and service fields.

• Bulk import — Paste .env-style KEY=VALUE pairs.

• From encrypted backup — Import a .credentials.enc file.

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

Credential files management showing configured and missing status

Credential Pattern

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

Export and Import

Export creates an encrypted .credentials.enc file for backup. Import decrypts and injects credentials from an encrypted file. Auto-import runs on agent startup via POST /api/internal/decrypt-and-inject.

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

Credential API

Endpoint	Method	Description
/api/agents/{name}/credentials/status	GET	Check credential files
/api/agents/{name}/credentials/inject	POST	Inject files directly
/api/agents/{name}/credentials/export	POST	Export to .credentials.enc
/api/agents/{name}/credentials/import	POST	Import from encrypted file

OAuth Credentials

OAuth2 authentication flows for connecting agents to external services like Google, Slack, GitHub, and Notion.

Open the agent's Credentials tab.

Click the OAuth provider button (Google, Slack, GitHub, or Notion).

Your browser redirects to the provider's authorization page.

After you approve access, credentials are normalized to MCP-compatible format and injected into the agent.

Supported Providers

• Google — Gmail, Calendar, Drive, and other Google Workspace services

• Slack — Workspace access for messaging and channel operations

• GitHub — Repository access, issues, pull requests

• Notion — Page and database access

OAuth tokens are stored in Redis with AOF persistence. When an OAuth flow completes, Trinity normalizes the token data, regenerates the agent's .mcp.json, and makes the credentials available to all configured MCP servers.

Subscription Credentials

Share Claude Max/Pro subscription tokens across multiple agents, with automatic assignment, health monitoring, and auto-switch on rate limits.

Key Concepts

•Subscription — A Claude Max or Pro subscription token registered with Trinity. Stored encrypted (AES-256-GCM).

•Round-Robin Assignment — New agents automatically get a subscription assigned. The subscription with the fewest agents is selected first.

•Auto-Switch — When an agent hits repeated rate-limit (429) errors, Trinity automatically switches it to a different subscription.

How It Works

Go to the Settings page.

In the Subscriptions section, click Register Subscription.

Enter a subscription name and token. The subscription is encrypted and stored.

Expand a subscription row to see assigned agents with assign/unassign controls.

Encryption Requirement

CREDENTIAL_ENCRYPTION_KEY must be set in .env. This is auto-generated by start.sh on fresh deployments. If missing, a warning banner appears on the Settings page, the Register button is disabled, and the API returns 503.

Subscription API

Endpoint	Method	Description
/api/subscriptions	GET	List all subscriptions
/api/subscriptions	POST	Register a subscription
/api/subscriptions/{id}/assign	POST	Assign to an agent
/api/subscriptions/{id}/unassign	POST	Unassign from an agent

Security Best Practices

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

✓Never commit .env or .mcp.jsonto git — only commit templates and encrypted files

✓Store the CREDENTIAL_ENCRYPTION_KEY separately from encrypted credential files

✓Use least-privilege API keys — grant only the scopes each agent needs

✓Rotate credentials regularly and revoke old keys immediately after rotation

Agent Configuration OAuth Credentials