> ## Documentation Index
> Fetch the complete documentation index at: https://teamcopilot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Management

> Learn how users add secrets in TeamCopilot, how skills and workflows reference them, and why the secret proxy model is safer than putting raw keys in agent context.

In TeamCopilot, users do not paste raw secrets into workflow files or skill instructions.

Instead, you store secrets in TeamCopilot, then reference them by key name from skills and workflows.

<Check>
  <strong>TeamCopilot never injects a secret into the LLM chat history.</strong> The model gets secret names and placeholders, while the real values are resolved only by trusted runtime layers at execution time.
</Check>

```mermaid theme={null}
flowchart TB
    A[Skill or workflow declares secret keys] --> B{User secret exists?}
    B -->|Yes| C[Use profile secret]
    B -->|No| D{Global secret exists?}
    D -->|Yes| E[Use global secret]
    D -->|No| F[Block run and show missing keys]
```

## What you need to do

If a skill or workflow needs a secret:

1. Open **Profile Secrets** in TeamCopilot.
2. Add the required key, such as `OPENAI_API_KEY` or `STRIPE_SECRET_KEY`.
3. Save it.
4. Retry the skill or workflow.

If your organization uses shared fallback secrets, an engineer can also add **Global Secrets**. Your personal secret overrides the global one when both use the same key.

## Where secrets live

TeamCopilot supports two secret scopes:

* **Profile Secrets**: your personal secrets for your own runs
* **Global Secrets**: shared fallback secrets managed by engineers

This gives teams a practical default:

* regular users add their own keys in **Profile Secrets**
* engineers can provide shared defaults in **Global Secrets**
* a user's personal key wins over the global key with the same name

That override model is useful when you want to test with your own account without changing the team's default credential.

## Profile Secrets UI

Users manage profile secrets from the dedicated `Profile Secrets` page in the app.

The page shows:

* the keys you have saved
* masked values in normal UI contexts
* actions to add, edit, or delete a key

## Global Secrets UI

Engineers manage global secrets from the same page, in a separate section.

That makes the common pattern straightforward:

* users add personal overrides
* engineers provide shared defaults
* the runtime resolves the best value at execution time

## How skills and workflows ask for secrets

Skills and workflows declare the secret keys they need by name.

### Skills

In `SKILL.md`, declare `required_secrets` in frontmatter and use `{{SECRET:KEY}}` placeholders in the content.

```yaml theme={null}
---
title: "Send campaign email"
required_secrets:
  - SENDGRID_API_KEY
---
```

```text theme={null}
Use this header in bash commands:
Authorization: Bearer {{SECRET:SENDGRID_API_KEY}}
```

### Workflows

In `workflow.json`, declare the required secret keys:

```json theme={null}
{
  "intent_summary": "Create an invoice in Stripe",
  "required_secrets": ["STRIPE_SECRET_KEY"]
}
```

Then read them in `run.py` as environment variables:

```python theme={null}
import os

stripe_key = os.environ["STRIPE_SECRET_KEY"]
```

If a required secret is missing, TeamCopilot tells the user which key to add in **Profile Secrets** before the skill or workflow can run.

## How TeamCopilot keeps secrets out of the model

The core rule is simple: the agent sees secret names, not secret values.

For bash-based usage, TeamCopilot uses a secret proxy pattern:

1. The skill or command references `{{SECRET:KEY}}`.
2. A trusted runtime layer checks where that placeholder is being used.
3. If the usage is allowed, TeamCopilot injects the real value only at execution time.
4. The raw value does not need to appear in the prompt, command text, or normal UI output.

For workflows, the workflow declares `required_secrets`, and TeamCopilot resolves those values for the current user at runtime.

For chat sessions, the app can also resolve secrets on demand for trusted runtime flows such as command execution or skill loading.

## Command support today

As of now, TeamCopilot also injects secret values for `curl` and `git` commands when the agent uses them through bash.

That means a command like:

```bash theme={null}
curl -H "Authorization: Bearer {{SECRET:API_TOKEN}}" https://example.com
```

or:

```bash theme={null}
git push https://{{SECRET:GIT_TOKEN}}@github.com/org/repo.git
```

can resolve the secret at execution time without exposing the raw value in chat history.

## Extending command support

If you want support for more bash commands, email `rishabh@trythis.app`, or create a [github pull request](https://github.com/rishabhpoddar/teamcopilot).

Another safe option is to wrap the command in a workflow. Workflows are pre-approved before use, so TeamCopilot can inject secrets into them however the workflow needs without exposing those values to the model.

## Runtime resolution order

The resolution order is:

1. profile secret
2. global secret fallback
3. missing-key error

That order makes personal overrides predictable without breaking shared defaults.

## What this protects against

This design is meant to reduce the most common AI-agent secret leaks.

* **Prompt injection**: if an attacker gets hidden instructions in front of the model, the model still does not have the plaintext key to leak
* **Unsafe command construction**: secret placeholders are only resolved in trusted positions; unsupported usage is rejected
* **UI exposure**: the frontend shows masked values instead of raw credentials
* **Cross-user leakage**: one user can use a shared or personal secret without seeing another user's actual key

## Engineer approval still matters

Workflows and skills can use secrets only after their code or instructions have been reviewed in TeamCopilot.

That approval step matters most for workflows, because workflows can use the resolved secret values directly in code. The trust boundary is the reviewed artifact plus the runtime that injects secrets without exposing them to the model.