Authentication

All customer endpoints require an API key. There are no anonymous endpoints.

Header

Authorization: Bearer sk_live_<your-secret>

The dashboard (app.syntheticusers.io) authenticates with Clerk and proxies API calls on your behalf — you only need to manage API keys for out-of-product use (CI, custom scripts, webhooks).

Minting a key

In the dashboard: API Keys → New key.

• The plaintext is shown exactly once. Lose it and you must mint a new one.
• Only the SHA-256 hash is stored on our side.
• What you can see afterward: the prefix (first 16 characters, e.g. sk_live_a1b2c3d4), name, and last_used_at.

// TypeScript fetch example
const res = await fetch(`${API_URL}/runs`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SYNTHUSERS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target_url: "https://staging.example.com",
    persona_ids: ["pers_..."],
  }),
});

Revoking a key

Dashboard → API Keys → click Revoke next to the key. Revocation is immediate (the next request returns 401 invalid_api_key).

Rate limits

Limits are per API key:

• Read requests (listing and fetching): 60 / minute.
• Cost-bearing requests (starting a run, importing personas from text): 10 / minute.

Going over either limit returns 429 rate_limited with a Retry-After header. Need higher limits? Mention it during onboarding — we lift caps case by case in early access.

Errors

Status	Code	Meaning
401	missing_auth	No Authorization header.
401	invalid_api_key	Key not recognised or revoked.
402	payment_required	Account is suspended (failed payment).
403	forbidden	Resource doesn’t belong to your customer.
429	rate_limited	Per-key throttle exceeded.

See errors for the full table.