Skip to content
Synthetic Users

Authenticated targets

If your staging URL requires a sign-in, you can give the agent a credential and it will fill the form. If signup requires an email confirmation, we give the agent a per-session email inbox at <session-id>@inbox.syntheticusers.io.

1. Store a credential

Credentials are envelope-encrypted at rest:

  • Master key lives in Cloudflare Workers Secrets.
  • Per-customer DEK encrypts each credential.
  • The plaintext is only decrypted inside the SessionDO at agent time, and is never returned in any API response (GET /credentials lists metadata only).
Terminal window
curl -s -X POST "$API_URL/credentials" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Vercel staging signup",
    "target_host": "vercel.com",
    "username": "[email protected]",
    "password": "<plaintext-paste-once>"
  }'
# → { "id": "cred_..." }

The target_host field is the SSRF allowlist key. A credential whose target_host does not match the run’s target_url host is rejected.

2. Use it in a run

Terminal window
curl -s -X POST "$API_URL/runs" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://vercel.com/signup",
    "persona_ids": ["pers_..."],
    "credential_ids": ["cred_..."]
  }'

If the agent reaches a login form, it fills it with the credential.

3. Email confirmation

Every session gets an isolated inbox at <session-id>@inbox.syntheticusers.io. The agent can:

  • Read the address via the get_email_address tool.
  • Block on the next message with check_email.
  • Click a URL inside the email body with click_link_in_email.

You don’t have to configure anything. As long as your signup flow emails a confirmation to the address the agent gave it, the inbox will catch it.

Transcript redaction

Stored transcripts strip credential values automatically. Emails delivered to the per-session inbox are visible inside the transcript (we need them for replay) but persona-supplied PII is masked before write (***@***.com, ***-***-****).

What we don’t support in V1

  • OAuth-into-customer-target flows (“Sign in with Google” against your product). Tracked for V1.5.
  • Persistent identity across runs. Each session is fresh; the agent doesn’t remember a previous session’s account.