Scoped Access Tokens

Scoped access tokens let you give each end user only the access they need to a browser session. Every token is tied to one scope: watch only, watch and interact through the live view, or full CDP control. For example, share a read-only live view with a customer watching an agent work, give a support engineer an interactive live view to take over, and keep CDP control in your own backend. Token URLs don’t include the session id, and you can revoke any token at any time.

Token scopes

Scope	URL field	The token holder can
`live_view_read_only`	`live_view_read_only_url`	Watch the browser. Mouse, keyboard and clipboard input is ignored.
`live_view`	`live_view_url`	Watch and interact with the browser.
`cdp`	`cdp_url`	Control the browser over CDP.

A read-only viewer and an interactive viewer can watch the same session at the same time. A live view token only opens the live view: it cannot connect over CDP or call the browser’s APIs.

Enable at session creation

Set session.scoped_access.active to true when you create a session. The response then carries one URL per scope, each with its own token:

import { client, Sessions } from 'anchorbrowser';

client.setConfig({ auth: () => process.env.ANCHOR_API_KEY });

const session = await Sessions.createSession({
  body: {
    session: {
      scoped_access: {
        active: true
      }
    }
  }
});

console.log(`Read-only live view: ${session.data.live_view_read_only_url}`);
console.log(`Interactive live view: ${session.data.live_view_url}`);
console.log(`CDP: ${session.data.cdp_url}`);

from anchorbrowser import Anchorbrowser
import os

client = Anchorbrowser(api_key=os.getenv("ANCHOR_API_KEY"))

session = client.sessions.create_session(
    session={
        "scoped_access": {
            "active": True
        }
    }
)

print(f"Read-only live view: {session.data.live_view_read_only_url}")
print(f"Interactive live view: {session.data.live_view_url}")
print(f"CDP: {session.data.cdp_url}")

Embed a live view URL in an iframe the same way as any other live view. If the session also sets live_view.read_only, no live view can interact: live_view_url is the same read-only URL as live_view_read_only_url, and cdp_url keeps full control.

Mint more tokens

To mint more token URLs for a running session, for example one per end user, call POST /v1/sessions/{session_id}/tokens. Pass scopes to choose which URLs to mint, or omit it for every URL the session can serve. Every call returns new tokens:

curl -X POST "https://api.anchorbrowser.io/v1/sessions/$SESSION_ID/tokens" \
  -H "anchor-api-key: $ANCHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["live_view_read_only"]}'

When scopes is omitted:

A headful session gets all three URLs.
A headless session gets only cdp_url, because live view tokens require a headful browser.
A live_view.one_time_url session gets no live_view_url.

Revoke a token

To revoke a token, pass the token from its URL to DELETE /v1/sessions/{session_id}/tokens/{token}. The URL stops opening new connections; a connection that is already open stays until it closes:

curl -X DELETE "https://api.anchorbrowser.io/v1/sessions/$SESSION_ID/tokens/$TOKEN" \
  -H "anchor-api-key: $ANCHOR_API_KEY"

Session id access

On a scoped session the session id is no longer a credential on its own: connecting to CDP or the live view with only ?sessionId= is refused. Connect with a token (?token=), or with the session id and a token (?sessionId=...&token=...). Any other session switches to tokens the same way as soon as you mint a token for it. Sessions that never use tokens keep working with the session id alone.

Minting a token on a session without scoped_access makes it token-only from then on: connections that are already open stay up, but new connections with only ?sessionId= are refused, so include cdp in scopes if your own code still connects. Revoking the tokens does not restore session id access.

Limitations

Tokens stop working when the session ends.
scoped_access requires a headful cloud browser and cannot be combined with live_view.one_time_url.
Batch and async session creation do not accept scoped_access. For those sessions, mint tokens with POST /v1/sessions/{session_id}/tokens once the session is running.
Tokens cannot be minted for sessions that run on a connector or a Mac.

Introduction

Platform

Integrations

Account

Token scopes

Enable at session creation

Mint more tokens

Revoke a token

Session id access

Limitations