# 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

| Rule | Example |
|------|---------|
| Start with a letter or underscore | `API_KEY`, `_INTERNAL_TOKEN` |
| Use letters, numbers, and underscores only | `GOOGLE_ADS_REFRESH_TOKEN` |
| Maximum 128 characters | — |
| Recommended: `UPPER_SNAKE_CASE` | `STRIPE_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:

```json
{
  "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 Secrets | Space Secrets |
|-|-------------|---------------|
| **Scope** | All agents in the organization | One Space only |
| **Managed from** | Settings → API keys & variables | CLI (`teamday spaces set-secret`) |
| **Reference syntax** | `teamday-secret:KEY` | `${VAR_NAME}` in `.mcp.json` |
| **Use case** | Shared API keys, org-wide tokens | Space-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:

```json
{
  "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

- [MCP Plugins](https://docs.teamday.ai/guides/mcp-plugins) — Connect external tools using org secrets for authentication
- [Space Setup](https://docs.teamday.ai/guides/space-setup) — Configure space-level secrets for per-project config
- [API Keys & Authentication](https://docs.teamday.ai/guides/api-keys) — Personal Access Tokens and Claude API credentials