Teamday

Docs · guides

Org Secrets

Store encrypted API keys, tokens, and runtime variables that any agent in your organization can use without exposing the raw value.

Org Secrets

Org secrets let you store encrypted API keys, tokens, and environment variables at the organization level. Once saved, any agent in your org can reference the secret by name — the raw value is never exposed to the agent, the browser, or logs.

Org secrets differ from space secrets: space secrets are scoped to one Space and managed via the CLI. Org secrets are shared across all agents and MCP connections in the organization and are managed from the Settings page.

Adding a Secret

  1. Go to Settings → API keys & variables in the left navigation.
  2. Click Add (or scroll to the Add a key or variable form on the right).
  3. Enter a name using UPPER_SNAKE_CASE — for example, GOOGLE_ADS_REFRESH_TOKEN.
  4. Paste the value (API key, token, or variable string).
  5. Optionally add a description so teammates know what the secret is for.
  6. Click Save.

The value is encrypted on save. Teamday returns only metadata (name, version count, last-used timestamp) — the stored value is never readable again through the UI.

Key Naming Rules

RuleExample
Start with a letter or underscoreAPI_KEY, _INTERNAL_TOKEN
Use letters, numbers, and underscores onlyGOOGLE_ADS_REFRESH_TOKEN
Maximum 128 characters—
Recommended: UPPER_SNAKE_CASESTRIPE_SECRET_KEY

Good names: OPENAI_API_KEY, HUBSPOT_OAUTH_TOKEN, DATAFORSEO_PASSWORD
Invalid names: my-key (hyphens), 123_KEY (starts with number), key with spaces

Referencing Secrets in Agent Instructions

To use a secret in an agent instruction, MCP header, or config string, write:

teamday-secret:YOUR_KEY_NAME

For example, to pass a key as an HTTP header in an MCP config:

{
  "headers": {
    "Authorization": "Bearer teamday-secret:OPENAI_API_KEY"
  }
}

At runtime, Teamday resolves teamday-secret:OPENAI_API_KEY to the stored value and injects it into the environment or header. The agent sees the resolved value as an environment variable — it never sees the literal teamday-secret:… string.

You can also reference secrets in agent instructions:

Use the token stored as teamday-secret:GOOGLE_ADS_REFRESH_TOKEN
to authenticate with the Google Ads API.

Secret Lifecycle

Versions: Each save increments the version counter. You can re-save a key at any time to rotate its value — existing jobs pick up the new value on the next run.

Last used: The "Last used" timestamp shows when a job last resolved this secret. Useful for identifying stale or unused credentials.

Deletion: Click Delete on any secret row. You'll be asked to confirm. Any MCP server or agent configuration that references the deleted key will stop working immediately.

Org Secrets vs Space Secrets

Org SecretsSpace Secrets
ScopeAll agents in the organizationOne Space only
Managed fromSettings → API keys & variablesCLI (teamday spaces set-secret)
Reference syntaxteamday-secret:KEY${VAR_NAME} in .mcp.json
Use caseShared API keys, org-wide tokensSpace-specific config, per-project keys

For secrets that every agent needs (company-wide API keys, billing tokens), use org secrets. For per-project or per-space configuration, use space secrets.

Common Use Cases

MCP server authentication

When you connect an MCP server that requires an API key in a header:

{
  "url": "https://api.example.com/mcp",
  "headers": {
    "X-API-Key": "teamday-secret:EXAMPLE_API_KEY"
  }
}

TeamDay's built-in connectors (Ahrefs, HubSpot, DataForSEO, etc.) store their OAuth tokens as org secrets automatically — you set them up once via the MCP catalog and they're available to all agents.

Environment variables for agent code

Any org secret is automatically injected as an environment variable into agent jobs. If you store STRIPE_SECRET_KEY, an agent running a Node.js script can read it as process.env.STRIPE_SECRET_KEY.

Rotating credentials

To rotate a key: open Settings → API keys & variables, find the row, click Update, paste the new value, and save. No agents need to be reconfigured — the reference (teamday-secret:KEY) stays the same.

Next Steps