Skip to main content

​
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

FieldTypeRequiredDescription
secretsarrayNoArray of secret entries to provide credentials for websites
secrets[].matchstringYesDomain pattern to match (e.g. *.salesforce.com) or all to match every site
secrets[].fieldsobjectYesKey-value pairs of credential fields (e.g. email, password, apiKey)

​
Request Example

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",
    initialTask: {
      taskDetails: "Log into Salesforce and export the open opportunities report",
      maxDuration: 10,
      maxInputTokens: 400000,
      maxOutputTokens: 200000,
      avoidDomains: [],
      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: "[email protected]",
            password: "secretpass"
          }
        },
        {
          match: "all",
          fields: {
            email: "[email protected]",
            password: "defaultpass"
          }
        }
      ]
    }
  })
}).then(r => r.json());

​
How Matching Works

The match field determines which websites the credentials apply to:
PatternMatches
*.salesforce.comAny subdomain of salesforce.com (e.g. login.salesforce.com, myorg.salesforce.com)
github.comExactly github.com
allAny 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

AspectSecretsGuardrails
When credentials are providedUpfront, at session creationOn-demand, when the agent asks
Task interruptionNone — agent authenticates seamlesslyTask pauses until you respond
AutomationFully automatedRequires a handler or human response
Best forKnown login targets, automated pipelinesDynamic 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: "[email protected]", password: "pass" } }
]

// Fallback — use 'all' only when needed as a catch-all
secrets: [
  { match: "*.salesforce.com", fields: { email: "[email protected]", password: "sfpass" } },
  { match: "all", fields: { email: "[email protected]", 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: 
{
  "initialTask": {
    "taskDetails": "Log in and export the report",
    "terminateOnCompletion": true,
    "secrets": [
      { "match": "*.example.com", "fields": { "email": "[email protected]", "password": "pass" } }
    ]
  }
}