Secrets

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, 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

const session = await fetch("https://api.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:

{
  "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 when you need to provide credentials interactively or handle unexpected login prompts.

Best Practices

Use Environment Variables

Never hardcode secrets in your source code:

// 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:

// 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:

{
  "task": {
    "prompt": "Log in and export the report",
    "terminateOnCompletion": true,
    "secrets": [
      { "match": "*.example.com", "fields": { "email": "user@co.com", "password": "pass" } }
    ]
  }
}

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Overview

Schema

Request Example

How Matching Works

Custom Fields

Security

Secrets vs Guardrails

Best Practices

Use Environment Variables

Use Specific Patterns

Combine with terminateOnCompletion

​Overview

​Schema

​Request Example

​How Matching Works

​Custom Fields

​Security

​Secrets vs Guardrails

​Best Practices

​Use Environment Variables

​Use Specific Patterns

​Combine with terminateOnCompletion

Handling Guardrails

Guardrails Concept

Parameters Reference

Cost Optimization

Overview

Schema

Request Example

How Matching Works

Custom Fields

Security

Secrets vs Guardrails

Best Practices

Use Environment Variables

Use Specific Patterns

Combine with terminateOnCompletion