Agent Onboarding

Choose a Path

• Signup with human approval: the agent asks, the human approves, the agent receives a scoped, spend-capped key that belongs to the human's account. Use it for ongoing work.
• Trial and claim link: no email, no approval. The agent gets 50 requests for 24 hours and a link its human opens to keep the same key. Use it to try AlterLab right now.
• x402 and MPP: no account and no key. The agent pays per request in USDC (x402) or from a prepaid Stripe session (MPP). Use it when there is no human to approve anything.

Signup with Human Approval

Start the request. email is optional: with it only that verified account can approve; without it, whoever opens the link and approves owns the key.

curl -X POST https://api.alterlab.io/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Acme Research Agent",
    "agent_url": "https://example.com/agent",
    "requested_scopes": ["scrape"]
  }'

The response holds signup_id, verification_url (also verification_uri_complete), user_code, poll_interval (5 seconds) and expires_in (900 seconds). Show the human the link and the code. Nothing exists until they approve: no account, key or balance, and no free credit is granted. With an email, the human also gets an approval email naming the agent, its permissions and the spend cap.

Poll until the status changes:

curl https://api.alterlab.io/api/v1/agent/signup/SIGNUP_ID

status is pending, approved, denied or expired. An expired request can be renewed once with POST /api/v1/agent/signup/{signup_id}/renew; after that, start a new one.

Receive the Key and Acknowledge

On approved the poll returns the scoped key as api_key, with a delivery_id, key_prefix, scopes, spend_cap_usd and redelivery_until. Store the key right away without printing it, then acknowledge:

curl -X POST https://api.alterlab.io/api/v1/agent/signup/SIGNUP_ID/ack \
  -H "Content-Type: application/json" \
  -d '{"delivery_id": "DELIVERY_ID"}'

Until you acknowledge, the same poll returns the same key for up to 10 minutes, so a lost response is recoverable. After the acknowledgement, or after 10 minutes, the key is gone and cannot be fetched again. The key is labeled "Agent: your agent name" and the human can revoke it from the dashboard.

Scopes and Spend Caps

requested_scopes takes up to eight of these values:

• scrape: read and write, so the agent can run scrapes and read jobs and results.
• read and write: read-only or submit-only access.
• hands:read, hands:write and hands:control: see and run browser tasks on the human's own connected sites, and pause, resume, stop or steer the tasks the agent started. Changes on a site wait for the human's approval.
• listings:write: create and publish Data Marketplace listings.

An agent key can never manage billing. It is capped at $5 per day by default, and the human can change or revoke it. The approval screen and the email show the exact permissions in plain language.

Rate Tiers and Web Bot Auth

Unverified agents are limited to 3 signup requests per IP per hour and 10 per agent name per hour. An agent that signs its request with Web Bot Auth (HTTP Message Signatures and a Signature-Agent header) is a verified agent and gets a higher tier: 30 per IP per hour and 200 per agent per hour. A single email address can receive 3 approval requests per hour either way.

Free Trial and Claim Link

curl -X POST https://api.alterlab.io/api/v1/agent/trial

No body, no account. The response returns a key (sk_trial_..., shown once), its request_cap of 50, an expires_at 24 hours out, and a claim_url and claim_message to relay to the human. Trial keys are limited to 3 per IP per day. Every later response from the key repeats the link in the X-AlterLab-Claim-URL header, including the trial-cap and trial-expired errors.

The human signs in or signs up and opens the claim link. The same key becomes theirs: the trial scope and expiry go away, standard read and write scopes and the daily spend cap apply, and it bills against their balance. The secret is rotated, so the human gives the agent the new key. The claim link is valid for 7 days. Claiming grants no credit of its own; signup credit comes from the normal signup flow.

x402 and MPP: Pay per Request with No Account

When enabled, send POST /api/v1/scrape with no credentials. The API answers 402 with a quote, and you pay to retry.

• x402 (USDC): the quote is in the PAYMENT-REQUIRED header (base64 JSON, exact scheme). Sign it and retry with PAYMENT-SIGNATURE. Payment settles only after a successful scrape and the receipt arrives in PAYMENT-RESPONSE.
• MPP (Stripe Shared Payment Token): the same 402 carries a WWW-Authenticate: Payment challenge for a $0.50 top-up. Retry with Authorization: Payment <credential>. The response returns X-AlterLab-Session and a Payment-Receipt. Send X-AlterLab-Session on later scrapes; each successful scrape is deducted in sub-cent amounts and failed scrapes cost nothing.

Requests that carry an API key or bearer token are never quoted. Keyless payment covers synchronous GET scrapes in auto, html and js modes and Data Marketplace listing runs; wallets on sanctions lists are refused. Full details are at alterlab.io/auth.md.

Errors

• 429 on signup or trial start: a rate limit was hit; wait for the Retry-After interval. Trial issuance returns this after 3 keys per IP in 24 hours.
• 404 on poll, renew or ack: the request is unknown, expired or already acknowledged.
• 409 on renew: the request was already renewed; start a new one.
• 403 with account_mismatch on approval: the signed-in account does not match the email the request names.
• 402 from a trial key: its 50-request cap is used up, and the error repeats the claim link. From an agent key it means the account balance is empty. With no key at all, 402 is the x402 and MPP quote described above.

MCP

The alterlab_create_account tool starts a signup. When an agent connects over MCP OAuth and the human ticks "Also create an API key for this machine" at consent, alterlab_create_api_key issues the key in one step. See the MCP guide for setup and API keys for key management.