Authenticated APIs

Some Parse APIs are built from sites that require login. These APIs have login endpoints that create sessions and protected endpoints that reuse the authenticated state. This page covers building one against a real account, then calling it.

Authenticated APIs are started from the Parse dashboard (check “This site needs a login” on the New API form) or programmatically over the API and MCP by setting allow_auth: true — after a one-time disclaimer acceptance in the dashboard. Free accounts cannot create authenticated APIs; paid plans include 5 or 10 logged-in accounts per site, and the limit can be raised on request.

Security overview

Parse signs in the same way you would, so the endpoints it builds see exactly the data and permissions of the account you connect. We recommend using a test account for initial builds where the site offers one. Parse is designed to ask for your permission before taking destructive actions, but building is an agentic process — an agent operates a real browser session on your account while it constructs endpoints — so we recommend still exercising caution, especially with accounts that can move money, place orders, or message other people.

Authenticated builds sign in to the target site as you. We assume you have reviewed that site’s terms of service and are authorized to access the account and its data this way. You are responsible for how your account is used; Parse accepts no liability for violations of a third-party site’s terms.

Credentials you provide are treated as secrets end to end:

A fresh keypair per build. Every build generates its own ephemeral RSA-4096 keypair. The public key is handed to your browser; the private key exists only for that build.
Encrypted before they leave your browser. Credentials are encrypted client-side with that build’s public key, so only that one build can read them.
Decrypted only in memory. The worker running your build decrypts them in memory to drive the login. They are never written to disk and never written to logs, and the private key is wiped from memory when the build finishes.
Network logs suppressed. Parse normally records the network requests behind a build for debugging. For authenticated builds that capture is turned off, so credentials in flight are never recorded.
Generated code is scanned before publish. Every authenticated build’s final code goes through an automated check — an LLM review plus pattern matching — that rejects code with hardcoded credentials. Your login is supplied at call time, not baked into the scraper.
Never shared publicly. Authenticated APIs are never contributed to the public marketplace. They stay private to your account.
Login attempts are rate-limited. Login endpoints are capped at 3 attempts per hour, counted per site per account.

Parse is currently undergoing a SOC 2 audit. The audit is in progress — we’re happy to share status with customers who need it; reach out from the dashboard.

Once the API is built, calls are protected separately: session state is encrypted with a key only you hold. See Security below.

How many accounts you can connect

A session is one account you’re logged into for a given site. The cap is counted per site, so being logged into two accounts on the same site uses two of them, while one account each on two different sites uses one apiece.

Your plan	Sessions per site
Free	None — authenticated APIs aren’t available
Paid plans	5
Higher-volume plans	10

Need more accounts on a site than your plan includes? Reach out to support with your use case, the website, and your expected needs — limits can be raised per account. We’ll need proof that you are authorized to control the accounts you use with Parse.

During the build: interactive prompts

Building against a login is a conversation. Rather than guessing, the agent pauses and asks you — in the dashboard, while the build is running:

Prompt	What it asks for	Expires after
Credential request	The username and password for the site	~5 minutes
2FA / one-time code	A code from your authenticator app, SMS, or email	~5 minutes
Clarifying question	A choice between options — e.g. “which employee should I use for the test?”	~15 minutes
Confirmation	Your go-ahead before a test action that could change or delete data	~15 minutes

If a prompt goes unanswered past its window it expires and the build parks — it stops where it is instead of guessing. Everything verified up to that point is kept (see below).

Credential and 2FA prompts are short-lived by design — a one-time code is usually only valid for a minute or two anyway. Stay on the build page while an authenticated build is running so you can answer promptly.

The dashboard is the easiest place to answer build-time prompts. A build started over the API pauses at status=needs_input; the simplest path is to open the build page and answer there, but you can also answer over the API. Never send build-time credentials through MCP chat — an MCP client hands you the build page URL instead. (Calling a finished API’s login endpoint with credentials over HTTP is a separate thing, and is covered below.)

Answering prompts over the API

While a build waits at status=needs_input, GET /dispatch/tasks/{task_id} returns the prompt on user_input_prompt: a request_id, the list of fields to fill, and a public_key_pem — a fresh RSA-4096 public key that exists only for this build. Responses are encrypted client-side against that key, exactly like the dashboard does:

Build the plaintext JSON object:

{
  "request_id": "<request_id from the prompt>",
  "outcome": "submitted",
  "values": { "<field name>": "<value>" },
  "user_note": ""
}

Generate a random 256-bit AES key and 12-byte IV, and encrypt the plaintext with AES-256-GCM (no additional authenticated data).
Wrap the AES key with the prompt’s public key using RSA-OAEP (SHA-256 hash, MGF1-SHA256, no label).
Submit the envelope — exactly these three keys, each base64-encoded:

curl -X POST https://api.parse.bot/dispatch/{task_id} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<request_id from the prompt>",
    "user_response": {
      "encrypted_key": "<base64 RSA-wrapped AES key>",
      "iv": "<base64 12-byte IV>",
      "ciphertext": "<base64 AES-GCM output>"
    }
  }'

The private key lives only in the worker running your build and is wiped when the build ends, so an envelope can never be decrypted later or by anyone else.

Keep credentials out of model context. If an agent is driving your integration, fetch secrets from a secret store inside your own code and encrypt them there — never paste credentials into an agent conversation or send them through MCP.

Endpoints are saved as they go

Endpoints are saved incrementally, as each one is verified — not in one batch at the end. Practically:

A build that fails partway through keeps the endpoints that already worked. You don’t lose the successful half of a build to a failure in the last step.
The same applies to a parked build waiting on a prompt that expired.
From there you continue or revise the API rather than starting over from scratch.

Incremental saving applies to new builds. Revisions to an existing API still apply their changes at completion.

Endpoint session tags

Each endpoint in an authenticated API has a session tag:

Tag	Meaning
`initiates_session: true`	Login endpoint. Returns `session_id` + `encryption_key` in the response.
`depends_on_session: "login"`	Protected endpoint. Requires `session_id` + `encryption_key` from a prior login call.
(neither)	Public endpoint. Works without any session, even on APIs that have other auth-gated endpoints.

curl -X POST https://api.parse.bot/scraper/{scraper_id}/login \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "s3cret"}'

The response includes your data plus two session values:

{
  "data": { "logged_in": true, "display_name": "Jane" },
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "encryption_key": "gAAAAABk..."
}

Store both session_id and encryption_key — you need them for every protected endpoint call. Parse does not store the encryption key.

Step 2: Call protected endpoints

Pass the session credentials via headers (preferred) or request body:

# Option A: Headers (recommended)
curl -X POST https://api.parse.bot/scraper/{scraper_id}/get_inbox \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Session-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Encryption-Key: gAAAAABk..." \
  -H "Content-Type: application/json" \
  -d '{"folder": "inbox", "limit": 10}'

# Option B: Body params
curl -X POST https://api.parse.bot/scraper/{scraper_id}/get_inbox \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-...",
    "encryption_key": "gAAAAABk...",
    "folder": "inbox",
    "limit": 10
  }'

The session state is automatically updated after each call — you don’t need to track cookies or tokens yourself.

Full example

import httpx

API_KEY = "your-api-key"
BASE = "https://api.parse.bot"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

scraper_id = "scraper-456"

with httpx.Client(headers=HEADERS, timeout=60) as client:
    # 1. Login
    resp = client.post(f"{BASE}/scraper/{scraper_id}/login", json={
        "username": "user@example.com",
        "password": "s3cret",
    })
    login = resp.json()
    session_id = login["session_id"]
    encryption_key = login["encryption_key"]

    # 2. Call a protected endpoint
    resp = client.post(
        f"{BASE}/scraper/{scraper_id}/get_inbox",
        headers={
            **HEADERS,
            "X-Session-ID": session_id,
            "X-Encryption-Key": encryption_key,
        },
        json={"folder": "inbox", "limit": 10},
    )
    print(resp.json())

Session details

One session per user per scraper: Logging in again with the same user upserts the existing session.
Proxy binding: The proxy IP used during login is reused for all protected endpoints to prevent session invalidation from IP changes.
Session updates are transparent: After each protected call, the session state is re-encrypted and saved automatically.
Rate limiting: Login endpoints enforce a rate limit of 3 login attempts per hour, counted per site per account — not per scraper. Several APIs built from the same site share one budget.

Error responses

Code	Detail	When
400	`This endpoint requires session_id and encryption_key. Call the login endpoint first.`	Protected endpoint called without session
400	`Invalid session or encryption key`	Wrong encryption key or corrupted session
404	`Session not found`	Invalid session_id or session belongs to a different scraper
403	Auth session limit reached	You’ve hit your per-site session cap

Security

At call time:

Fernet session encryption: Session state is encrypted with your encryption_key before storage. Parse stores only ciphertext — without your key, the data is unreadable.
HMAC replay protection: Serialized session blobs are signed with a 30-minute TTL.
No plaintext credential storage: Credentials provided during API creation are encrypted end-to-end and never stored in plaintext.

At build time: credentials are encrypted in your browser against a per-build RSA-4096 key, decrypted only in the worker’s memory, kept out of disk and logs, and scanned out of the generated code before publish. Authenticated APIs are never published to the marketplace. See the security overview for the full picture.

Getting Started

Features

Reference

Authenticated APIs

Security overview

How many accounts you can connect

During the build: interactive prompts

Answering prompts over the API

Endpoints are saved as they go

Endpoint session tags

Step 2: Call protected endpoints

Full example

Session details

Error responses

Security

​Security overview

​How many accounts you can connect

​During the build: interactive prompts

​Answering prompts over the API

​Endpoints are saved as they go

​Endpoint session tags

​Step 1: Call the login endpoint

​Step 2: Call protected endpoints

​Full example

​Session details

​Error responses

​Security

Security overview

How many accounts you can connect

During the build: interactive prompts

Answering prompts over the API

Endpoints are saved as they go

Endpoint session tags

Step 1: Call the login endpoint

Step 2: Call protected endpoints

Full example

Session details

Error responses

Security