# secrets

> Store values your agent uses but never shows, such as tokens.

Store values that Bash uses but never shows, such as your MCP servers' tokens or your users' own credentials. Secrets are write-only: once stored, a secret is never shown again, not even to you.

## TypeScript

```ts
// Store a company secret. Your MCP servers refer to it as ${secret:TRIPNEST_MCP_TOKEN}.
await vestra.secrets.set('TRIPNEST_MCP_TOKEN', process.env.TRIPNEST_MCP_TOKEN!);

// Store a user's secret. It is for their own account, as ${user_secret:IRCTC_TOKEN}.
await vestra.user('traveller-42').secrets.set('IRCTC_TOKEN', irctcToken);

// List and delete secrets. The list shows names only, never values.
const names = await vestra.secrets.list();
console.log(names.data.map((s) => s.name));
await vestra.secrets.delete('TRIPNEST_MCP_TOKEN');
```

## Python

```python
# Store a company secret. Your MCP servers refer to it as ${secret:TRIPNEST_MCP_TOKEN}.
vestra.secrets.set("TRIPNEST_MCP_TOKEN", os.environ["TRIPNEST_MCP_TOKEN"])

# Store a user's secret. It is for their own account, as ${user_secret:IRCTC_TOKEN}.
vestra.user("traveller-42").secrets.set("IRCTC_TOKEN", irctc_token)

# List and delete secrets. The list shows names only, never values.
print([s.name for s in vestra.secrets.list().data])
vestra.secrets.delete("TRIPNEST_MCP_TOKEN")
```

## CLI

```bash
# Store a company secret. Type the value when asked. From a script, pass --value - with the value on stdin, or
# --value-from-env <VAR>. The value is never part of the command, where it would stay in your shell history.
vestra secrets set TRIPNEST_MCP_TOKEN

# Store a user's secret. It is for their own account.
vestra secrets set IRCTC_TOKEN --user traveller-42

# List and delete secrets. The list shows names only, never values.
vestra secrets
vestra secrets delete TRIPNEST_MCP_TOKEN
```

## HTTP

```bash
# Store a company secret. Your MCP servers refer to it as ${secret:TRIPNEST_MCP_TOKEN}.
curl -X PUT "$VESTRA_BASE_URL/v1/secrets/TRIPNEST_MCP_TOKEN" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "your-token" }'

# Store a user's secret. It is for their own account, as ${user_secret:IRCTC_TOKEN}.
curl -X PUT "$VESTRA_BASE_URL/v1/secrets/IRCTC_TOKEN" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "value": "token-from-their-account" }'

# List and delete secrets. The list shows names only, never values.
curl "$VESTRA_BASE_URL/v1/secrets" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/secrets/TRIPNEST_MCP_TOKEN" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

## MCP

Only people manage secrets: no MCP tool stores or lists one. Use the console, the CLI or HTTP.

## Good to know

### Company and user secrets

A secret stored without a user belongs to your company. Refer to it as `${secret:NAME}`. A secret stored with a user belongs to that user. Refer to it as `${user_secret:NAME}`.

### Listing secrets

Listing secrets returns their names, never their values.

### The key you need

Managing secrets needs a key with the `setup` scope, or `all`.

## The routes behind secrets

- `PUT` [/v1/secrets/{name}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/put-v1-secrets-name.md): Store a secret, write-only: the company's (refer to it as ${secret:NAME}), or with user_id one user's own (${user_secret:NAME}), for example their travel account token. Storing it again replaces it. Key scope: `setup` (or `all`).
- `DELETE` [/v1/secrets/{name}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/delete-v1-secrets-name.md): Remove one: the company's, or one user's (user_id). Key scope: `setup` (or `all`).
- `GET` [/v1/secrets](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/get-v1-secrets.md): Secret names, never the values: the company's, or one user's (user_id). Key scope: `setup` (or `all`).

Next: [`mcp`](https://vestra.ai/developers/mcp.md)