Cookie & Header Authentication

Test-Lab can inject cookies and HTTP headers before running tests, allowing you to test authenticated areas without the AI agent needing to log in manually.

Use Cases

• Session cookies - Test logged-in user flows
• Auth tokens - Access protected API endpoints
• Feature flags - Test specific feature variations
• Bypass tokens - Skip CAPTCHA or rate limiting during tests

Cookie Hierarchy

Cookies can be configured at three levels, with later levels overriding earlier ones:

Project cookies → Test Plan cookies → Runtime cookies (API)

Cookie Configuration

Required Fields

Domain Patterns

The domain field determines which URLs receive the cookie:

Examples

Wildcard domain (recommended):

{
  "name": "auth_token",
  "value": "eyJhbGciOiJIUzI1NiIs...",
  "domain": ".myapp.com"
}

This cookie will be sent to myapp.com, www.myapp.com, api.myapp.com, etc.

Specific subdomain:

{
  "name": "admin_session",
  "value": "admin_xyz789",
  "domain": ".admin.myapp.com"
}

This cookie will only be sent to admin.myapp.com and its subdomains.

Configuring in the Dashboard

Project-Level Cookies

1. Go to Projects in the admin dashboard
2. Click Edit on your project
3. Expand Advanced Settings
4. Add cookies under the Cookies section
5. Click Save

All test plans in this project will inherit these cookies.

Test Plan-Level Cookies

1. Go to Test Plans in the admin dashboard
2. Click Edit on your test plan
3. Expand Advanced Settings
4. Add cookies (these override project cookies with the same name)
5. Click Save

Configuring via API

Pass cookies at runtime when triggering tests:

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanIds": [123],
    "cookies": [
      {
        "name": "session",
        "value": "dynamic_token_from_ci",
        "domain": ".myapp.com"
      }
    ]
  }'

Runtime cookies override any cookies configured in the dashboard.

CI/CD Integration

Generate fresh auth tokens in your CI pipeline and pass them to Test-Lab:

GitHub Actions Example

- name: Get auth token
  id: auth
  run: |
    TOKEN=$(curl -X POST https://myapp.com/api/login \
      -d '{"email":"test@example.com","password":"${{ secrets.TEST_PASSWORD }}"}' \
      | jq -r '.token')
    echo "token=$TOKEN" >> $GITHUB_OUTPUT

- name: Run Test-Lab tests
  run: |
    curl -X POST https://test-lab.ai/api/v1/run \
      -H "Authorization: Bearer ${{ secrets.TESTLAB_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "testPlanIds": [123],
        "buildId": "${{ github.sha }}",
        "cookies": [
          {
            "name": "auth_token",
            "value": "${{ steps.auth.outputs.token }}",
            "domain": ".myapp.com"
          }
        ]
      }'

Troubleshooting

Cookies not working?

1. Check the domain - Use .example.com (with leading dot) for subdomains
2. Verify the cookie name - Must match exactly what your app expects
3. Check for typos in value - Copy-paste to avoid errors
4. Test manually first - Verify the cookie works in your browser's DevTools

Test still shows login page?

• Your app may require additional cookies (e.g., CSRF tokens)
• The cookie may have expired server-side
• Check if your app validates other headers or conditions

Header Authentication

HTTP headers are useful for API authentication or when your app expects tokens in request headers rather than cookies.

Use Cases

• Bearer tokens - Authorization: Bearer <token>
• API keys - X-API-Key: <key>
• Custom auth headers - Any header your app expects

Header Configuration

Headers are simple name-value pairs:

Which Requests Get Your Headers

By default a header is only sent to the site you are testing: the domain of the test's URL and all of its subdomains. If your test opens https://www.example.com, requests to www.example.com, app.example.com and api.example.com carry your headers, while third-party requests (fonts, analytics, CDNs on other domains) do not. When a test targets several sites, every site it names is included.

To choose exactly where a header goes, fill in its Hosts field (comma-separated, up to 20 patterns). When set, the header is sent only to those hosts instead of the default:

Typical use: your app at app.example.com calls an API on a different domain such as api.example-cloud.com. Leave Hosts empty for headers your site needs, and set api.example-cloud.com (or app.example.com, api.example-cloud.com if both need it) on the API's header. Wildcards must name a real domain: *.com is rejected.

Headers are added after the browser's CORS checks, so a custom header never triggers a CORS preflight. Your app's own cross-origin API calls (for example app.example.com calling api.example.com) keep working even if the API's Access-Control-Allow-Headers does not list your header.

Header Hierarchy

Like cookies, headers can be configured at three levels:

Environment headers -> Test Plan headers -> Runtime headers (API, CLI, MCP)

More specific levels override less specific ones (by header name, case-insensitive).

Configuring in the Dashboard

Environment-Level Headers

1. Go to Projects in the admin dashboard and open your project
2. Edit the environment (for a new project, expand Test config under its production environment)
3. Add headers under the HTTP Headers section
4. Click Save

Every test plan run against that environment uses these headers.

Test Plan-Level Headers

1. Go to Test Plans in the admin dashboard
2. Click Edit on your test plan
3. Expand Advanced Settings
4. Add headers (these override environment headers with the same name)
5. Click Save

Runtime Headers (API, CLI, MCP)

Pass headers for a single run when triggering tests, for example a short-lived token your CI just generated. Runtime headers are not stored, and they override environment and plan headers with the same name. Each one accepts the same optional hosts patterns as stored headers.

curl -X POST https://www.test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanIds": [123],
    "headers": [
      { "name": "Authorization", "value": "Bearer dynamic_token_from_ci" },
      { "name": "X-Api-Key", "value": "{{credentials.apiKey}}", "hosts": ["api.example-cloud.com"] }
    ]
  }'

With the CLI, use --header (repeatable) or --headers with a JSON array:

testlab run 123 --header "Authorization: Bearer $TOKEN_FROM_CI"
testlab run 123 --headers '[{"name":"X-Api-Key","value":"{{credentials.apiKey}}","hosts":"api.example-cloud.com"}]'

With the MCP server, pass headers to the run_tests tool:

{ "testPlanIds": [123], "headers": [{ "name": "Authorization", "value": "Bearer ..." }] }

Header values can reference stored credentials ({{credentials.<key>}}), so a secret never has to appear on the command line.

Using Credentials in Headers

Reference stored credentials to avoid hardcoding sensitive values:

{
  "name": "Authorization",
  "value": "Bearer {{credentials.api_token}}"
}

See Credentials for more on secure value injection.

Common Header Patterns

Bearer token:

{
  "name": "Authorization",
  "value": "Bearer {{credentials.auth_token}}"
}

API key:

{
  "name": "X-API-Key",
  "value": "{{credentials.api_key}}"
}

Basic auth:

{
  "name": "Authorization",
  "value": "Basic {{credentials.basic_auth}}"
}

Next Steps