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

Managing multiple API tokens​

Create additional API tokens so you can use a separate token per application, environment, or team member and revoke any one of them without affecting the others.

  1. On your account home page, find the API Key section and click Manage API keys
  2. Review the list of your existing tokens

Only account owners and admins can manage tokens, and each account can hold up to 20 tokens.

Create a token​

  1. Click Create API key
  2. Enter a name for the token. Choose any label that helps you recognize where it's used.
  3. Confirm to generate the token

If you've reached the 20-token limit, revoke a token you no longer use before creating a new one.

warning

Your new token is shown only once, at creation time. Copy it and store it somewhere secure right away. If you lose it, you can't view it again and must create a new one.

Revoke a token​

  1. Find the token you want to remove in the list
  2. Click Revoke

Revoking a token invalidates it immediately, and any application using that token stops working. For a planned rotation, update those applications to use a valid token before you revoke. If a token is compromised, revoke it right away, then update your applications.

You can't revoke your last remaining token. Create a replacement first, then revoke the old one. Your account always keeps one token designated as the primary (the one shown on your account home page); if you revoke the primary, another active token is automatically promoted to take its place.

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​

How you rotate depends on what your dashboard shows.

Accounts with multiple tokens​

If your account home page shows a Manage API keys link, rotate without downtime: create a new token, update your applications to use it, then revoke the old one. See Managing multiple API tokens.

Accounts with a single token​

If your account home page shows a single API key with a Change API Key button, use that button 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
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 this way:

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

  • Create a separate API key per environment or application so you can revoke one without disrupting the others
  • 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