Passing Secrets

When you embed the widget, each end user likely needs the agent to connect to their data — their database, their API, their tenant. Environment variables and secrets let you pass per-user credentials at token exchange time so the agent’s MCP servers connect to the right services for each end user.

How It Works

Your Backend                        Sigmic AI                          Agent Sandbox
     |                                   |                                |
     | 1. POST /api/v1/auth/token        |                                |
     |   { env: { TENANT_ID: "acme" },   |                                |
     |     secrets: { API_KEY: "sk-…" } } |                                |
     |---------------------------------->|                                |
     |   Stores env + secrets            |                                |
     |   server-side (encrypted)         |                                |
     |                                   |                                |
     |                                   | 2. User sends a message        |
     |                                   |   (Authorization: Bearer JWT)  |
     |                                   |                                |
     |                                   | 3. Retrieves stored env+secrets|
     |                                   |   Injects into MCP server      |
     |                                   |   configuration                |
     |                                   |------------------------------->|
     |                                   |   {{mcp.KEY}} → actual value   |

Your backend passes env and secrets when exchanging credentials for a widget JWT
Sigmic AI stores them server-side — secrets are encrypted at rest. Neither env nor secrets are included in the JWT itself or sent to the browser.
When the user chats, the platform retrieves the stored values and injects them into every MCP server in the project. Template placeholders like {{mcp.API_KEY}} in your server config are resolved to the actual values before the connection is established.

`env` vs `secrets`

Both env and secrets are key-value string maps passed in the token exchange request. The difference is how they are stored:

	`env`	`secrets`
Storage	Encrypted at rest	Encrypted at rest
Returned in API responses	Never	Never
Sent to the browser	Never	Never
Use for	Tenant IDs, regions, feature flags	API tokens, database URLs, passwords
Available as	`{{mcp.KEY}}` in MCP config	`{{mcp.KEY}}` in MCP config

If the same key appears in both env and secrets, the secrets value takes precedence.

The env/secrets distinction exists for forward compatibility. Today both are stored securely. Use secrets for anything sensitive (tokens, passwords, connection strings) and env for non-sensitive configuration (tenant IDs, regions, feature flags).

Using Variables in MCP Server Config

MCP servers are configured in your project settings (via the Console or the project config API). Use {{mcp.KEY}} placeholders in the server’s headers, env, or url fields. These placeholders are resolved at runtime using the env/secrets from the active widget token.

Example: HTTP server with API key in headers

Step 1 — Configure the MCP server in your project:

curl -X PUT "https://api.sigmic.ai/api/users/you/projects/my-project/config/mcp/my-api-server" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mcp.example.com/v1",
    "type": "http",
    "headers": {
      "Authorization": "Bearer {{mcp.MY_API_TOKEN}}",
      "X-Tenant-ID": "{{mcp.TENANT_ID}}"
    },
    "enabled": true
  }'

{
  "url": "https://mcp.example.com/v1",
  "type": "http",
  "headers": {
    "Authorization": "Bearer {{mcp.MY_API_TOKEN}}",
    "X-Tenant-ID": "{{mcp.TENANT_ID}}"
  },
  "enabled": true
}

Step 2 — Pass the values when issuing a widget token:

// Your backend — token exchange
const response = await fetch('https://api.sigmic.ai/api/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId: process.env.SIGMIC_APP_ID,
    appSecret: process.env.SIGMIC_APP_SECRET,
    endUserId: 'user-123',
    env: {
      TENANT_ID: currentUser.tenantId
    },
    secrets: {
      MY_API_TOKEN: currentUser.apiToken
    }
  })
});

Result: When the agent connects to my-api-server, the headers are resolved to:

Authorization: Bearer sk-actual-token-value
X-Tenant-ID: acme-corp

Example: stdio server with environment variables

MCP server config:

{
  "command": "npx",
  "args": ["-y", "@your-org/db-mcp-server"],
  "type": "stdio",
  "env": {
    "DATABASE_URL": "{{mcp.DATABASE_URL}}",
    "SCHEMA": "{{mcp.DB_SCHEMA}}"
  },
  "enabled": true
}

Widget token request:

const response = await fetch('https://api.sigmic.ai/api/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId: process.env.SIGMIC_APP_ID,
    appSecret: process.env.SIGMIC_APP_SECRET,
    endUserId: 'user-123',
    env: { DB_SCHEMA: 'public' },
    secrets: { DATABASE_URL: 'postgres://user:pass@host/acme_db' }
  })
});

Result: The MCP server process launches with these environment variables:

DATABASE_URL=postgres://user:pass@host/acme_db
SCHEMA=public

Example: SSE server with dynamic URL

{
  "url": "https://{{mcp.REGION}}.analytics.example.com/mcp/sse",
  "type": "sse",
  "headers": {
    "X-API-Key": "{{mcp.ANALYTICS_KEY}}"
  },
  "enabled": true
}

With env: { REGION: 'us-east-1' } and secrets: { ANALYTICS_KEY: 'ak-12345' }, the agent connects to https://us-east-1.analytics.example.com/mcp/sse with header X-API-Key: ak-12345.

Template Reference

Aspect	Detail
Syntax	`{{mcp.KEY_NAME}}`
Supported fields	`headers`, `env`, and `url` in MCP server configs
Resolution timing	When the MCP server connection is established (not at token issuance)
Missing keys	The server fails to connect with an error naming the placeholder and the keys that were available. The agent is told the integration is misconfigured (it will not ask your end user for credentials), and the Console flags the mismatch — see Troubleshooting
Case	Names are case-sensitive: `{{mcp.API_TOKEN}}` does not match a secret named `api_TOKEN`
Scope	All MCP servers in the project receive the same set of variables

Key naming rules

Keys must be valid environment variable names:

Start with a letter or underscore
Contain only letters, digits, and underscores
All values must be strings

Valid	Invalid
`TENANT_ID`	`123-invalid` (starts with digit)
`API_KEY`	`has-dashes` (contains hyphens)
`db_url`	`has spaces` (contains spaces)
`_INTERNAL`	`key.with.dots` (contains dots)

Troubleshooting placeholders

A placeholder only resolves when the key name in your MCP server config matches, character for character, a key your backend sent in env or secrets when it minted the widget token. When a placeholder cannot be resolved:

In the agent session the MCP server fails to connect instead of sending the literal placeholder. The error names the server, the field, the placeholder and the keys that were available, for example: MCP server 'billing-api' (headers.Authorization): unresolved template variable {{mcp.API_TOKEN}} (did you mean 'api_TOKEN'?). Available keys: api_TOKEN. Keys are case-sensitive. The agent tells the end user the integration is misconfigured; it does not ask them for credentials.
In the Console (Project → Settings → MCP Servers) the health check for a server that uses placeholders cannot test the connection — the values only exist inside a widget session — so it reports the placeholders it found and, once your backend has minted at least one token with env/secrets, whether each placeholder matches a key that was actually sent. Saving a server config returns the same check as warnings in the response.
On each widget app (Project → Settings → Widgets) the Console shows the key names your backend has sent with env/secrets on token mints so far (accumulated, so end users with different key sets do not hide each other). Values are never stored for display. Sessions started through the Task API carry their own env/secrets and are not recorded here.

Fix it by renaming either side so they match exactly. Prefer upper-case names such as API_TOKEN on both sides.

Multi-Tenant Example

A common pattern is passing per-tenant credentials so each end user’s widget session connects the agent to that user’s data:

// Express backend — /api/sigmic-chat/token
app.post('/api/sigmic-chat/token', async (req, res) => {
  // 1. Authenticate your own user
  const user = await authenticateRequest(req);

  // 2. Look up tenant-specific config
  const tenant = await db.tenants.findById(user.tenantId);

  // 3. Exchange for widget JWT with tenant-scoped context
  const response = await fetch('https://api.sigmic.ai/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      appId: process.env.SIGMIC_APP_ID,
      appSecret: process.env.SIGMIC_APP_SECRET,
      endUserId: user.id,
      expiresIn: '1h',
      env: {
        TENANT_ID: tenant.id,
        TENANT_NAME: tenant.name,
        REGION: tenant.region
      },
      secrets: {
        DATABASE_URL: tenant.databaseUrl,
        API_TOKEN: tenant.apiToken
      }
    })
  });

  const data = await response.json();
  res.json({ token: data.data.token });
});

With the corresponding project MCP server config:

{
  "tenant-api": {
    "url": "https://{{mcp.REGION}}.api.example.com/mcp",
    "type": "http",
    "headers": {
      "Authorization": "Bearer {{mcp.API_TOKEN}}",
      "X-Tenant-ID": "{{mcp.TENANT_ID}}"
    },
    "enabled": true
  },
  "tenant-db": {
    "command": "npx",
    "args": ["-y", "@your-org/postgres-mcp"],
    "type": "stdio",
    "env": {
      "DATABASE_URL": "{{mcp.DATABASE_URL}}"
    },
    "enabled": true
  }
}

Each end user’s widget session connects the agent to that user’s database and API — with credentials that never leave the server.

Token Refresh and Variables

Each widget token has its own set of env/secrets. When you refresh a token, you must pass env and secrets again — the new token does not inherit values from the previous one. This also means you can update credentials on refresh without interrupting the session. For example, if an end user’s API key is rotated, the next token refresh can include the new key.

// fetchToken callback — re-fetch credentials on every refresh
fetchToken: async function() {
  const response = await fetch('/api/sigmic-chat/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: currentUser.id })
  });
  const data = await response.json();
  return data.token;  // Backend re-fetches tenant credentials each time
}

Security

env and secrets are never included in the JWT — they are stored server-side only
They are never sent to the browser — the widget iframe only receives the JWT
Values are stored encrypted and automatically cleaned up when the token expires
Secrets are only decrypted when the agent session needs them

This is the same mechanism used by the Task API for passing environment variables. If you are already using env/secrets with the Task API, they work identically in the widget.

Getting Started

Chat UI

Embeddable Widget

Task API

Concepts

Examples

How It Works

`env` vs `secrets`

Using Variables in MCP Server Config

Example: HTTP server with API key in headers

Example: stdio server with environment variables

Example: SSE server with dynamic URL

Template Reference

Key naming rules

Troubleshooting placeholders

Multi-Tenant Example

Token Refresh and Variables

Security

​How It Works

​env vs secrets

​Using Variables in MCP Server Config

​Example: HTTP server with API key in headers

​Example: stdio server with environment variables

​Example: SSE server with dynamic URL

​Template Reference

​Key naming rules

​Troubleshooting placeholders

​Multi-Tenant Example

​Token Refresh and Variables

​Security

How It Works

`env` vs `secrets`

Using Variables in MCP Server Config

Example: HTTP server with API key in headers

Example: stdio server with environment variables

Example: SSE server with dynamic URL

Template Reference

Key naming rules

Troubleshooting placeholders

Multi-Tenant Example

Token Refresh and Variables

Security