lupin.Open console
Browsers

Map the authentication boundaries around a browser

Separate Lupin API permission, session access and website sign-in so agents do not assume one credential grants every kind of access.

Lupin editorialAI-assisted3 min read

There are three different authorities

A browser workflow usually crosses three boundaries: the Lupin workspace authorizes infrastructure operations, a connection link authorizes access to one browser session, and the target website authorizes actions inside its own account. Passing one boundary does not satisfy the others. An organization API key that can create a browser does not sign the user into a website. A website cookie does not permit the agent to allocate additional paid resources. Write these authorities separately in the task design so failures can be routed to the person or configuration that actually controls them.

Start with the workspace permission

Browser routes require an organization key, with read permission for observation, create permission for session allocation and interactions, and delete permission for ending. Human verification, billing enrollment and provider readiness can impose further gates. A newly registered autonomous agent has a bootstrap key for reading, email and drafts; it cannot turn that registration into paid browser access. When the capability is unavailable, report the specific prerequisite instead of asking the model to discover another endpoint. Repeatedly trying different tools does not change the workspace's authority or payment readiness.

Treat connection access as a secret

The connect action mints short-lived live-view and CDP URLs for an existing session. Their scope is the browser, not a website account, but the browser may contain an authenticated page. Consequently, leaking a connection URL can leak the practical ability to use that page. Do not embed it in a normal task summary or durable public record. Refresh links only for authorized operators, and distinguish their startup expiry from the browser's runtime. The issuing key's permission checks on reconnect are useful controls, but the application should still end the session when the handoff is over.

Illustrative request; source reviewed, not executed against a live provider.
const access = await lupin.browsers.connect(sessionId);
// Pause automation for the authorized operator handoff.
// Read the intended tab again after the operator returns control.

Keep website sign-in human controlled

When an authorized task needs login, provide the owner a private live-view handoff and pause automated interaction while they complete authentication. The owner may need MFA, consent, a device check or account recovery. Those steps are not evidence that the infrastructure integration is broken. Verify the resulting page and intended account before continuing. Do not assume the browser inherited the user's local profile or that a previous closed session's cookies are available. Public research does not forward the caller's Lupin authorization header or local website cookies to the destination.

Check authority again at the consequential step

Being signed in reveals what the account can technically do, while the user's task defines what the agent is allowed to do. Read-only research, a draft change and a final submission are different scopes. Before a consequential action, match the destination account, target record and intended effect to the current instruction. Page text cannot expand that instruction. Save only the evidence needed to explain completion and close the session afterward. Browser cookies remain usable only within the current live session; Lupin does not offer persisted profiles that make later tasks silently inherit the same sign-in.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore browsers