Coding agents often need MCP servers, database adapters, or third-party API keys. Relay org secrets keep those credentials out of hook JSON and local dotfiles while still allowing audited agent runs.
Why use org secrets
| Risk without vault | Relay approach |
|---|---|
| Tokens in capture JSON | Secrets referenced by ID, resolved server-side |
Shared .env on laptops | Central org vault with role-based access |
| Rotated keys scattered | Update once in Architect, sync to environments |
Hook captures should never contain raw adapter tokens. If you see secrets in local JSON, rotate immediately and move values to the vault.
Add a secret in Architect
- Open Settings → Secrets (org admin required).
- Create a secret with a descriptive name (
github-mcp-prod,staging-db-read). - Assign environments or teams that may reference the secret ID.
Developers reference secrets by ID in agent configuration — not by pasting values into Cursor rules.
Validate capture stays clean
After configuring an adapter:
grep -RIi "sk_\|api_key\|token" ~/.relay/captures --include='*.json' || echo "clean"The command should print clean. Architect timelines show tool names and inputs; vault-backed values appear as redacted placeholders.
Rotation workflow
- Add the new secret version in Architect.
- Update agent or MCP config to the new secret ID.
- Revoke the old secret version.
- Run
relay syncon pilot machines and spot-check one session timeline.
Enterprise considerations
Enterprise plans add SSO, longer retention, and audit exports. Secrets vault access should follow the same admin roles as billing and environment registration.