Token Roles and Permissions

Enterprise Browserless uses a token-based permission system with four roles. Each token carries a single role that determines what the holder can do.

Roles

Role	Description
admin	Full access. Can run browser traffic, view metrics, manage configuration, and create or delete other tokens.
developer	Can run browser traffic (connect browsers, create sessions, call REST APIs) and view metrics. Cannot create, view, or delete other tokens.
viewer	Can view metrics, load configuration, and see active sessions. Cannot connect browsers or call REST APIs.
public	URL-based access for resources explicitly marked as public.

Default Behavior

The root TOKEN environment variable receives the admin role automatically on first startup. You set this variable in your Docker configuration or through the dashboard. All other tokens are created through the management API below.

Tokens persist to disk and survive container restarts. Each token stores a createdAt Unix timestamp (milliseconds) and a createdBy field containing the full token string of the admin that created it.

Token Management API

Create and delete operations require an admin token. Non-admin tokens receive 401 Unauthorized.

List All Tokens

Any authenticated token can list tokens.

curl -X GET "https://chrome.browserless.io/tokens?token=YOUR_API_TOKEN_HERE"

Returns an array of token objects:

[
  {
    "token": "abc123-your-admin-token",
    "permissions": "admin",
    "createdAt": 1736935800000,
    "createdBy": "abc123-your-admin-token"
  },
  {
    "token": "def456-your-developer-token",
    "permissions": "developer",
    "createdAt": 1740063600000,
    "createdBy": "abc123-your-admin-token"
  }
]

Each object contains a token field (the token string), permissions (the role), createdAt (Unix timestamp in milliseconds), and createdBy (the full token string of the admin that created it).

Create a Token

curl -X POST "https://chrome.browserless.io/token?token=YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"permission": "developer", "label": "scraping-team"}'

The permission field (singular) accepts admin, developer, viewer, or public. The optional label field attaches a human-readable name to the token. The response returns the full token object:

{
  "token": "ghi789-new-developer-token",
  "permissions": "developer",
  "label": "scraping-team",
  "createdAt": 1743015600000,
  "createdBy": "abc123-your-admin-token"
}

Delete a Token

curl -X DELETE "https://chrome.browserless.io/token/def456-your-developer-token?token=YOUR_API_TOKEN_HERE"

Replace def456-your-developer-token with the token value from the list endpoint. Returns 204 No Content on success.