Skip to main content
Inject cookies into a user’s browser session to enable authenticated browsing without interactive login. This endpoint accepts Playwright-format cookie objects and is disabled by default for security.

​
Endpoint

POST /sessions/:userId/cookies

​
Authentication

This endpoint requires the CAMOFOX_API_KEY environment variable.
​
Authorization
string
required
Bearer token matching the CAMOFOX_API_KEY environment variable:
Authorization: Bearer YOUR_CAMOFOX_API_KEY
If CAMOFOX_API_KEY is not set, all requests to this endpoint return 403 Forbidden.

​
Path parameters

​
userId
string
required
Unique user identifier. Cookies are scoped to this user’s browser session. All tabs created with this userId will share these cookies.

​
Request body

​
cookies
object[]
required
Array of Playwright-format cookie objects. Maximum 500 cookies per request.

​
Response

​
ok
boolean
true if cookies were imported successfully
​
userId
string
User ID that received the cookies (normalized to string)
​
count
number
Number of cookies imported

​
Error response

​
error
string
Human-readable error message
​
invalid
object[]
When cookie validation fails, this array contains details about invalid cookies:

​
Security

​
Why authentication is required

Cookie injection moves the browser from anonymous browsing to authenticated browsing. This endpoint:
  • Is disabled by default (returns 403 if CAMOFOX_API_KEY is not set)
  • Requires a secret Bearer token to prevent unauthorized cookie injection
  • Uses timing-safe comparison to prevent timing attacks on the API key

​
Setup

1. Generate a secret API key: 
openssl rand -hex 32
2. Set the environment variable before starting the server: 
export CAMOFOX_API_KEY="your-generated-key-here"
npm start
3. Send the key in the Authorization header: 
curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-generated-key-here' \
  -d '{"cookies": [...]}'

​
Validation and sanitization

​
Required fields

Each cookie object must include:
  • name (non-empty string)
  • value (string)
  • domain (non-empty string)
Requests with invalid cookies return 400 Bad Request with details in the invalid array.

​
Field allowlist

Only these Playwright cookie fields are accepted:
  • name, value, domain, path, expires, httpOnly, secure, sameSite
All other fields are stripped during sanitization.

​
Limits

  • Maximum 500 cookies per request - returns 400 if exceeded
  • Maximum 512KB request body - enforced by Express
  • No domain filtering - cookies are injected as-is (ensure your cookie domain matches the sites you’ll browse)

​
Examples

curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
  -d '{
    "cookies": [
      {
        "name": "session_token",
        "value": "abc123xyz789",
        "domain": ".example.com",
        "path": "/",
        "expires": -1,
        "httpOnly": true,
        "secure": true,
        "sameSite": "Lax"
      }
    ]
  }'
Response: 
{
  "ok": true,
  "userId": "agent1",
  "count": 1
}

​
Multiple cookies

curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
  -d '{
    "cookies": [
      {
        "name": "li_at",
        "value": "AQEDATP...",
        "domain": ".linkedin.com",
        "path": "/",
        "expires": 1735689600,
        "httpOnly": true,
        "secure": true
      },
      {
        "name": "JSESSIONID",
        "value": "ajax:1234567890",
        "domain": ".linkedin.com",
        "path": "/",
        "expires": -1,
        "httpOnly": true,
        "secure": true
      }
    ]
  }'
Response: 
{
  "ok": true,
  "userId": "agent1",
  "count": 2
}

​
Error: Missing required fields

curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
  -d '{
    "cookies": [
      {"name": "foo"},
      {"value": "bar", "domain": "example.com"}
    ]
  }'
Response (400 Bad Request): 
{
  "error": "Invalid cookie objects: each cookie must include name, value, and domain",
  "invalid": [
    {"index": 0, "missing": ["value", "domain"]},
    {"index": 1, "missing": ["name"]}
  ]
}

​
Error: Authentication disabled

{
  "error": "Cookie import is disabled. Set CAMOFOX_API_KEY to enable this endpoint."
}

​
Error: Invalid Bearer token

{
  "error": "Forbidden"
}

​
Error: Too many cookies

{
  "error": "Too many cookies. Maximum 500 per request."
}

​
Workflow

  1. Export cookies from your browser using a browser extension (e.g., “cookies.txt” for Chrome/Firefox)
  2. Parse Netscape format into Playwright cookie objects (if using OpenClaw, the plugin does this automatically)
  3. Send cookies to the server with the Bearer token
  4. Create tabs with the same userId - they will inherit the injected cookies
  5. Navigate to authenticated pages - the browser session is now logged in

​
Use cases

  • Skip interactive login flows on sites like LinkedIn, Amazon, Twitter
  • Preserve authentication state across sessions
  • Automate tasks that require login without exposing credentials
  • Test authenticated workflows with AI agents

​
Session lifecycle

Cookies are scoped to the user’s browser session:
  • All tabs created with userId share the same cookies
  • Sessions expire after 30 minutes of inactivity (configurable via SESSION_TIMEOUT_MS)
  • Cookies persist until session expires or is explicitly closed via DELETE /sessions/:userId
  • New cookie imports merge with existing cookies (duplicate names are overwritten)

​
Limitations

  • Cookies are stored in-memory (not persisted to disk)
  • No built-in Netscape format parser - convert to Playwright format first
  • Domain filtering is not enforced - ensure cookie domains match your target sites
  • The endpoint does not validate cookie expiration dates

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us