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

API Key Management

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

Accessing Your API Key​

  1. Log in to your account at browserless.io/account
  2. Your API key is displayed on the account home page under the API Key section
  3. Click the Copy button next to your key 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.

tip

See Best Practices for guidance on storing your API key securely using environment variables and secrets managers.

Rotating Your API Key​

If your API key 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 key:

  • 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 Keys Securely​

  • Use environment variables to store your API key rather than hardcoding it in source files
  • Never commit API keys 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 key 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