For AI agents: a documentation index is available at /llms.txt
Skip to main content

API Token Management

Your API token authenticates all requests to Browserless services. Manage your token from the Browserless dashboard.

Accessing your API token​

  1. Log in to your account at browserless.io/account
  2. Your API token is displayed on the account home page under the API Key section
  3. Click the Copy button next to your token to copy it to your clipboard

Using your API token​

Add your API token to the URL query string as ?token=YOUR_TOKEN. Invalid tokens result in HTTP 401 or 403 responses. Keep the URL secure and avoid exposing it in client-side code or logs.

Example:

https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE

Rotating your API token​

If your API token has been compromised or you want to rotate it as a security best practice, use the Change API Key button in the dashboard.

Steps to rotate​

  1. Navigate to browserless.io/account
  2. Click the Change API Key button
  3. Review the confirmation dialog carefully
  4. Click Change API Key to confirm

What happens during rotation​

warning

Changing your API token requires a few minutes of downtime, and you will need to update all your applications to use the new token.

When you rotate your API token:

  • Your current key is immediately invalidated
  • A new randomly-generated key is created
  • The new key is displayed on your account page
  • All active connections using the old key will stop working
  • You must update the token in every application or service that connects to Browserless

Plan your rotation during a maintenance window to minimize disruption to your services.

Best Practices​

Store tokens securely​

  • Use environment variables to store your API token rather than hardcoding it in source files
  • Never commit API tokens to version control (add .env files to .gitignore)
  • Use a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or 1Password) for production deployments

Example: using environment variables​

# .env file (never commit this)
BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE
// Access the token from your environment
const token = process.env.BROWSERLESS_TOKEN;
const url = `https://production-sfo.browserless.io/scrape?token=${token}`;
import os

token = os.environ["BROWSERLESS_TOKEN"]
url = f"https://production-sfo.browserless.io/scrape?token={token}"

Rotation frequency​

  • Rotate your API token immediately if you suspect it has been compromised
  • Rotate periodically (every 90 days) as a security best practice
  • Rotate when team members with access leave your organization
  • Rotate after revoking access from any third-party integration

Limit exposure​

  • Use separate credentials per environment where possible (for example, separate Browserless accounts if multiple keys are not available on your plan)
  • Monitor your usage dashboard for unexpected activity
  • Avoid sharing your key across multiple unrelated projects

FAQ & Troubleshooting​

How do I get started with Browserless?

Sign up for a free account at browserless.io, get your API token, and follow the Quickstart guide for BQL or the BaaS guide for Puppeteer/Playwright.

What's the difference between BQL and BaaS?

BQL is a GraphQL API for declarative browser automation with built-in stealth. BaaS runs your existing Puppeteer or Playwright scripts on managed browsers. See comparison for details.

Next steps​

Dashboard

view, copy, and rotate your API token

API Comparison

learn about authentication across Browserless APIs

BQL Quickstart

use your token to run your first BrowserQL query