Authentication & API keys

This page covers WebAgent's API key format, how to send it on every request, and the create / revoke / rotate flow.

Every request carries a bearer token in the Authorization header:

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxx

Key shape

• Prefix: wa_ — short for web agent. (Mirrors Stripe's sk_*.)
• Length: 28+ chars after the prefix. Treat them as opaque.
• Scope: one project. Multi-project? Create one key per project.
• Visibility: shown once at creation. Lose it → revoke and create again.
• Revocation: soft-delete with a one-hour grace window so in-flight requests don't 401 mid-task.

Where to keep it

• Local dev: environment variable, .env.local (already in .gitignore).
• Production: your secret manager (Vault, AWS Secrets Manager, GCP Secret Manager, …).
• Never commit a key to git. The Console's Get Code dialog uses a placeholder by default.

Multi-project

A single user can have many projects. The API path encodes the project:

GET /v1/projects/{project_id}/do_anything/sessions

There is no X-Project-Id header. The path makes the tenant explicit so a stray curl to a different project ID is a different URL — no silent cross-tenant calls.

Rotation

You can keep two valid keys at once. Common rotation flow:

1. Create a new key in Settings → API Keys.
2. Deploy with the new key.
3. Revoke the old one. Old key keeps working for one hour; deploy completes; old key 401s after the grace window.

Errors

Status	Code	Meaning
401	unauthorized	Missing, malformed, expired, or revoked-past-grace
403	forbidden	Key valid but doesn't have access to that project
429	rate_limit_exceeded	Per-key concurrency or per-minute limit hit

Next steps

• Pricing & Credits — what each task costs.
• Sessions & Tasks — what a request actually creates.