Credentials

For a short workflow, start with testing an authenticated user journey.

How Verify signs in

A Verify credential is a dedicated test account: a login identity, such as Billing admin or Free-plan member, that runs use to sign in to your app. Each credential records the sign-in method, account identity, and when to use it. Runs test signed-in journeys as that user.

Open your project's Credentials to add and manage them. Organization administrators can create, edit, disable and delete credentials; other members can see their names, sign-in method and guidance, never their secrets.

Composal offers two kinds of credential:

• Managed credentials: Composal stores what a run needs to sign in, encrypted. This can be a password with an optional authenticator seed, a dedicated email inbox, a saved browser session or a passkey. They work with any app.
• Better Auth sign-in: your app trusts Composal as a sign-in provider. Composal stores no password or cookie, and each run receives a short-lived token for the persona it tests. Create as many personas as you have roles.

Choose a sign-in method

• Composal sign-in: your app uses Better Auth 1.7 or later. Composal keeps the persona's name, its cred.composal.ai address and your app's provider settings, but no secret for your app.
• Password: your app has an email or username and password form, optionally with authenticator-app 2FA or emailed codes. Composal keeps the password and authenticator setup key, encrypted, and can give the credential a Composal address whose inbox runs can read.
• Email link / OTP: your app signs in with magic links or emailed codes, or you test signup. Composal creates a dedicated inbox that runs can read.
• Sign in with a browser or Session cookies: sign-in needs a human step, such as SSO, a CAPTCHA or a push approval. Composal keeps an app session for one origin, valid for 24 hours.
• Passkey: your app signs in with passkeys. Composal keeps an enrolled software passkey for one origin, valid for 30 days.
• Google or GitHub: your app offers that provider's sign-in button. Composal keeps the provider test account's password and authenticator setup key.
• Custom: sign-in needs extra steps, such as choosing a workspace. Composal keeps a password and your written instructions.

If you control a Better Auth app, prefer Composal sign-in: there is nothing to rotate or expire, and agents never handle a password. Otherwise prefer a password with an authenticator setup key. Use saved sessions when a person must complete sign-in. If Cloudflare Turnstile blocks recurring automated sign-in, configure a signed Verify request exemption in your app.

Where credentials apply

Credentials belong to a project and work on every environment in it, including its pull request previews. Runs in other projects never receive them.

When starting Deep Scan or Discovery, choose a configured project credential in Credential, including Email link / OTP accounts. The browser agents can read that account's inbox for sign-in links and codes. Disabled or incomplete credentials are excluded; choose Anonymous — no login to explore without signing in.

When you prepare a run from the latest definitions, Verify checks whether the credential's login URL points to another saved environment in the same project. If it does, Verify uses the selected environment's origin while preserving the login path, query and fragment. An external identity provider keeps its own login URL. This changes the prepared run only; the saved credential stays unchanged. Replaying saved definitions preserves the source run's login address.

A saved session or passkey is bound to the origin it was saved for, so it isn't offered on an environment or preview with another origin. Composal sign-in follows a preview automatically.

How runs use credentials

When you prepare a run, Verify chooses one credential for each scenario:

1. When the scenario's persona has its own Credential, that credential is always used.
2. Otherwise Verify chooses among the project's ready credentials that no other persona has claimed and that fit the environment. A single credential is used directly. With several, Verify picks the best match from the persona, the scenario and each credential's name and When to Use description.
3. A scenario that needs to sign in fails preparation when no ready credential is available, rather than running signed out. A signup persona needs its own fresh email-link inbox as its credential.

The chosen credential and its saved versions are pinned when you approve the run. If someone edits or disables it afterwards, the run stops instead of signing in with different values.

During the run, the agent sees only references to the credential's fields, such as its username and password keys, and the credential's sign-in guidance. The browser supervisor fills the values into the page. Browser sessions, passkeys and Composal sign-in are installed before the scenario starts, and agents can never type them into a page.

Runs sharing an account with an authenticator, emailed sign-in code or cloud passkey wait for that account's turn. Verify can reuse an app session from an earlier run, while keeping the account's password and authenticator available for another sign-in. Unrelated accounts can run in parallel.

Security

• Passwords, authenticator seeds, sessions and passkeys are encrypted and write-only: the app, API and CLI never return them.
• A run receives only the credential selected for it, after its lease is verified, and only for its duration.
• Credential values are redacted from diagnostics and model observations. Recordings show pages as the agent saw them, so use dedicated test accounts.
• Disabling a credential blocks it for all future runs. It does not sign out a browser that is already signed in.

Next, set up managed credentials or Better Auth sign-in.