Browser

Oya Browser docs

Personas, CAPTCHA and MFA

A persona is one identity: a fingerprint, a cookie jar and a proxy, bound together. How to create one, rotate between personas, solve CAPTCHAs and complete MFA.

Personas

A persona is one identity: a fingerprint, a cookie jar and a proxy, bound together and stable for its life. One persona is one device.

There are two ways to get caught, and they are mirror images of each other:

ShapeSignal
One account seen from many device fingerprintsTextbook bot farm
One device fingerprint across many accounts, or 1,000 concurrent sessionsDevice farm

Binding the fingerprint to your API key avoids the first and walks straight into the second. Binding it to each browser avoids the second and walks into the first. So the binding sits at the level that actually corresponds to a device:

Example
persona = fingerprint + cookie jar + proxy       # one identity, one device
API key = a group of personas                    # your fleet

A persona's fingerprint is derived from a stored seed, so it is byte-identical across restarts, a returning session looks like a returning device, not a new one.

Example
const p = await oya.personas.create({ name: "acme-ops" });
const browser = await oya.browser.start({ persona: p.id });

await oya.personas.list();     // includes activeBrowsers and maxConcurrent
await oya.personas.remove(p.id);
Every API key has a default persona whose seed reproduces the fingerprint that key had before personas existed. If you run a single account, nothing changed for you.

Rotation and concurrency

Rotation means picking a different persona, never giving one persona a new fingerprint. persona: 'auto' selects the least recently used persona that is still under its concurrency cap.

Concurrency is capped per persona, because one laptop cannot be in a thousand places at once. Named personas default to 2 (a phone and a laptop is plausible); the default persona is uncapped so an existing fleet does not break on upgrade. Past the cap you get a clear 429 rather than a silent breach, and activeBrowsers is visible in the dashboard and as a Prometheus metric.

CAPTCHA

Example
await browser.solveCaptcha();                    // explicit
oya.browser.start({ captcha: 'auto' });          // solve as they appear

Detects reCAPTCHA v2/v3, hCaptcha and Turnstile. Providers that solve natively, Anchor, Browserbase, Steel, Browser Use, are left to do it rather than paying twice and racing their attempt. Everything else goes to your configured solver (CapSolver or 2Captcha).

Returns { solved, method: 'provider' | 'solver' | 'none' }. A failure returns solved: false: a silent no-op that leaves an agent stuck is worse than a clear answer.

Automated solving conflicts with some sites' terms of service. Sessions that used it are recorded in the audit trail so you can see which.

MFA

Example
await oya.personas.setMfa(id, { type: 'totp', secret: 'JBSWY3DPEHPK3PXP' });
await oya.personas.setMfa(id, { type: 'email', url: 'https://mail.example/api/latest' });

const r = await browser.completeMfa();
if (!r.completed) open(r.liveViewUrl);   // finish it by hand

TOTP is generated locally (RFC 6238). Email and SMS one-time codes are polled from a relay endpoint you supply, within a bounded window, because the code does not exist yet when the prompt appears. When nothing automated can answer, liveViewUrl is where a person finishes; that is also the only workable answer for push-approval MFA.

TOTP seeds are credential material of the same weight as a password: sealed at rest with AES-256-GCM, audited on use, and never returned by the API. The relay URL is checked against private and link-local ranges when you store it and on every poll, because a public name says nothing about where it resolves later.