Authentication

All WebUplink API requests require a Bearer token in the Authorization header.

API Keys

API keys are provisioned through the dashboard. They start with wup_ and should be kept secret.

# Set as environment variable
export WEBUPLINK_API_KEY="wup_your_key_here"

SDK Configuration

import { WebUplink } from 'webuplink';

const client = new WebUplink({
  apiKey: process.env.WEBUPLINK_API_KEY!,
  baseUrl: 'https://api.webuplink.ai',
});

Direct HTTP

curl -X POST https://api.webuplink.ai/v1/browse \
  -H "Authorization: Bearer wup_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

When your agent browses a login page, the engine generates tools like login or sign_in with username/password parameters — just like any other page tool. After your agent executes the login tool, the session retains authenticated state (cookies, tokens) for the rest of that session. Sessions are ephemeral — ~2 minutes idle, ~15 minutes maximum — so auth state never outlives the task: start a fresh session and execute the login tool again for the next one (see Sessions). Credentials passed as tool parameters exist only for the duration of that request.

const page = await client.browse({
  url: 'https://app.example.com/login',
  tool: 'login',
  params: { username: 'jane@example.com', password: process.env.SITE_PASSWORD! },
});

How it works: The engine perceives the login form and generates a callable tool. The executor fills the form fields and submits. The session's browser retains the resulting cookies — no credential storage, no magic.

Login automation is verification-gated (not a plan feature): it's available on every plan, including Free — add a card to your account (a $0 verification — you're not charged) and attest to the Acceptable Use Policy from dashboard → billing. Dedicated identity-provider domains — accounts.google.com, login.microsoftonline.com, appleid.apple.com, and similar SSO providers — return DOMAIN_BLOCKED (403) until it's enabled. The same AUP terms cover sites that render their own login form (like the example above): automate sign-ins only for accounts you own or are expressly authorized to operate, and the target site's terms remain your responsibility. Accounts that abuse login automation are suspended from the capability automatically.

Expectations and limits

Automated logins can be interrupted by defenses the target site controls:

CAPTCHAs. WebUplink does not solve or bypass CAPTCHAs — automated solving is disabled when every browser session is created. A login flow that presents one cannot complete.
Two-factor authentication. Flows that push approval to another device or demand a one-time code from another channel will interrupt the login.
Device verification. Every WebUplink session is a fresh, isolated browser, so "new device" and "unrecognized browser" checks fire more often than they would in a personal browser.

When a site serves a bot-verification challenge or an access-denied page instead of content, the request fails with SITE_BLOCKED (502, not retryable) and no actions are billed. The error message names which kind of block it was — a challenge or an access denial — and retrying from the same infrastructure hits the same wall, so treat the page as unsupported rather than retrying. See Production Traffic & Bot Detection for the full story.

Security Best Practices

Never commit API keys to version control
Use environment variables or a secrets manager
Rotate keys if they may have been exposed
Use the minimum plan that meets your needs

Playground Tokens

The documentation playground uses scoped tokens with limited permissions:

Browse-only — Can observe pages but cannot execute tools
30-minute TTL — Automatically expire
No billing access — Cannot view usage or manage subscriptions

Playground tokens are intended for the docs site only. Use your full API key for production integrations.

Authentication

On this page