> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Secrets
> Provide credentials securely to the agent for website authentication during task execution
## Overview
When your agent needs to log into websites or authenticate with services during task execution, you can provide credentials using the `secrets` parameter. Secrets are matched to websites by domain pattern, so the agent uses the right credentials for each site it visits.
Secrets are **never stored** in a database or persisted anywhere. They are only loaded and attached to the active session, then **immediately discarded** once the session is destroyed.
This approach eliminates the need for [guardrail-based credential handling](/usage-guides/handling-guardrails#1-login-credentials), where the agent pauses and waits for you to provide login details mid-task. With secrets, the agent can authenticate automatically without interruption.
***
## Schema
| Field | Type | Required | Description |
| ------------------ | -------- | -------- | ------------------------------------------------------------------------------ |
| `secrets` | `array` | No | Array of secret entries to provide credentials for websites |
| `secrets[].match` | `string` | Yes | Domain pattern to match (e.g. `*.salesforce.com`) or `all` to match every site |
| `secrets[].fields` | `object` | Yes | Key-value pairs of credential fields (e.g. `email`, `password`, `apiKey`) |
***
## Request Example
```javascript theme={null}
const session = await fetch("https://connect.webrun.ai/start/start-session", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${API_KEY}`
},
body: JSON.stringify({
mode: "default",
task: {
prompt: "Log into Salesforce and export the open opportunities report",
maxDuration: 10,
maxInputTokens: 400000,
maxOutputTokens: 200000,
outputType: "structured_json",
outputSchema: {
type: "object",
properties: {
opportunities: {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string" },
amount: { type: "number" },
stage: { type: "string" }
}
}
}
},
additionalProperties: false
},
secrets: [
{
match: "*.salesforce.com",
fields: {
email: "user@company.com",
password: "secretpass"
}
},
{
match: "all",
fields: {
email: "user@company.com",
password: "defaultpass"
}
}
]
}
})
}).then(r => r.json());
```
***
## How Matching Works
The `match` field determines which websites the credentials apply to:
| Pattern | Matches |
| ------------------ | ------------------------------------------------------------------------------------- |
| `*.salesforce.com` | Any subdomain of salesforce.com (e.g. `login.salesforce.com`, `myorg.salesforce.com`) |
| `github.com` | Exactly `github.com` |
| `all` | Any website the agent visits — used as a fallback |
When multiple secrets match a domain, the more specific pattern takes priority over `all`.
***
## Custom Fields
The `fields` object supports arbitrary key-value pairs. Use field names that correspond to the login form fields on the target website:
```json theme={null}
{
"match": "*.example.com",
"fields": {
"username": "admin",
"password": "secretpass",
"otp_secret": "JBSWY3DPEHPK3PXP",
"api_key": "sk-abc123"
}
}
```
***
## Security
Secrets are transmitted securely and are **never** included in task output or webhook payloads. They are only used by the agent during browser automation to fill in authentication forms.
Key security properties:
* **No persistence** — Secrets are never stored in a database or written to disk. They exist only in the session's memory.
* **Session-scoped** — Secrets are attached to the session at creation and immediately discarded when the session is destroyed.
* **Not in output** — Secrets never appear in task results, webhook payloads, or logs.
* **Encrypted in transit** — All API communication uses HTTPS/TLS.
***
## Secrets vs Guardrails
| Aspect | Secrets | Guardrails |
| --------------------------------- | ---------------------------------------- | ------------------------------------ |
| **When credentials are provided** | Upfront, at session creation | On-demand, when the agent asks |
| **Task interruption** | None — agent authenticates automatically | Task pauses until you respond |
| **Automation** | Fully automated | Requires a handler or human response |
| **Best for** | Known login targets, automated pipelines | Dynamic or unpredictable auth flows |
Use secrets when you know which sites the agent will authenticate with. Use [guardrails](/usage-guides/handling-guardrails) when you need to provide credentials interactively or handle unexpected login prompts.
***
## Best Practices
### Use Environment Variables
Never hardcode secrets in your source code:
```javascript theme={null}
// Bad
secrets: [{ match: "*.example.com", fields: { password: "hardcoded123" } }]
// Good
secrets: [{ match: "*.example.com", fields: { password: process.env.EXAMPLE_PASSWORD } }]
```
### Use Specific Patterns
Prefer specific domain patterns over `all` to limit credential exposure:
```javascript theme={null}
// Targeted — credentials only sent to Salesforce
secrets: [
{ match: "*.salesforce.com", fields: { email: "user@co.com", password: "pass" } }
]
// Fallback — use 'all' only when needed as a catch-all
secrets: [
{ match: "*.salesforce.com", fields: { email: "sf@co.com", password: "sfpass" } },
{ match: "all", fields: { email: "default@co.com", password: "defaultpass" } }
]
```
### Combine with terminateOnCompletion
For single-use authenticated tasks, terminate the session immediately after completion to ensure secrets are discarded as soon as possible:
```javascript theme={null}
{
"task": {
"prompt": "Log in and export the report",
"terminateOnCompletion": true,
"secrets": [
{ "match": "*.example.com", "fields": { "email": "user@co.com", "password": "pass" } }
]
}
}
```
***
Interactive credential handling when secrets aren't set
How guardrails work and when they trigger
Complete API parameter documentation
Reduce costs with session management