Managed credentials

Add a credential

Composal encrypts and stores managed credentials for runs to use when signing in. Use them with any app. For a Better Auth app, Better Auth sign-in avoids storing anything for your app.

1. Open your project's Credentials and choose Add Credential.
2. Choose how agents sign in: Sign in with a browser, Password, Email link / OTP or Session cookies. Google, GitHub, Passkey and Custom are also visible under More sign-in methods.
3. Give the credential a Name that says who it is, such as Staging admin, and fill in the method's fields below.
4. Optional: open the instructions section to add When to Use, such as Use for admin and billing journeys, and Login Instructions, such as Choose the Acme workspace. Login is complete when the dashboard is visible. Verify uses the first to choose between credentials and gives the second to the agent.
5. Choose Save test account.

Password and authenticator

Choose Password for an email or username and password form. Enter the Login page, the Email / Username and the Password.

For authenticator-app 2FA, open Instructions and two-factor authentication and enter the Authenticator Secret: the Base32 setup key or otpauth:// URI your app shows when you enroll an authenticator, not a one-time code. Agents generate a fresh code each time they sign in. Runs that share an authenticator sign in one at a time, so a code is never reused.

The first run to sign in shares its signed-in app session. Later scenarios can reuse that copy in their own browsers, while keeping the password and authenticator available if they need to sign in again. Runs on that account still wait for its sign-in turn, so they cannot use its authenticator concurrently. Unrelated accounts can run in parallel.

If the copy is signed out, for example after a scenario logs out, it is discarded. A run with the account's password and authenticator can sign in again. A copy lasts up to two hours and is deleted when the account is edited or disabled.

The run page shows whether the first run shared its session and, when it could not, why; the account's other scenarios show that they are waiting for its sign-in turn.

If your app emails a verification link or a two-factor code after the password, turn on Use a Composal Email Address. Saving creates a Composal address in place of the username and shows it with an Inbox button. Sign up on your app with that address, open the verification email in the credential's Inbox, then edit the credential and save the password you chose. The credential shows Needs Password until then. During a run, the agent signs in with the address and password, then reads the emailed code or link from that inbox, with the same limits as an email-link credential.

Push approvals, SMS codes and other provider challenges need a person. Use a saved browser session for those apps.

Email link and one-time codes

Choose Email link / OTP for apps that sign in with magic links or emailed codes. Saving creates a dedicated Composal email address and shows it on the credential. Register or invite that address in your app before you run scenarios with it.

During a run, the agent requests a sign-in email and then reads that inbox to open the link or enter the code. It can read only messages that arrive after its run started, and only for the credential selected for that run. Scenarios that test signup need their own fresh inbox: assign one email-link credential to the signup persona for each signup you test. Once a scenario starts with that credential, Verify refuses another signup with it, including a run approved earlier. Create and assign a fresh inbox before preparing another signup; Verify does not create a new inbox automatically for each run.

For a multi-persona journey whose sign-in email opens a separate authentication host, an administrator can configure email_link_auth_origins through the project credential API. Keep login_url pointing to the app's public sign-in or signup page. List the additional exact origins, such as https://auth.example.com, without paths, query strings, fragments or wildcards; an email-link credential accepts up to 20. The default is an empty list.

Save a request file containing the non-secret origin configuration, then update the credential:

{
  "email_link_auth_origins": ["https://auth.example.com"]
}

com api request verify project-credentials update --org your-org --project your-project \
  --id vaccount_example --body-file auth-origins.json --json

Prepare a new run after changing this setting. Verify captures the permitted login-mail origins for that actor; changing the origin policy during execution stops private-mail access. Invitation links keep their existing origin rules. This flow requires matching Rails, Roder and browser support; an older browser image refuses the additional grant before sign-in.

Google, GitHub and custom login

Google and GitHub describe your app's "Continue with Google" or "Continue with GitHub" button. They do not create a Composal OAuth integration. Enter a dedicated provider test account's email and password, and its authenticator setup key if it uses 2FA. Google may refuse sign-in from an automated browser. If it does, sign in yourself and save the app session instead; provider cookies are never accepted.

Custom is a password login with extra steps. Its Login Instructions are required; describe each step and how to recognize that sign-in succeeded.

Saved browser sessions

A saved session lets runs start already signed in, after you complete sign-in yourself, including SSO, CAPTCHAs or push approvals. Composal saves only the app's cookies, local storage and IndexedDB for one origin. Sessions expire after 24 hours, or earlier if your app signs them out, so refresh them before you run.

To sign in from Composal:

1. Choose Add Credential → Sign in with a browser. Enter the Account Name and the app's HTTPS App Login URL, then choose Start Login Browser.
2. Choose Open Login Browser and sign in, including any MFA. The private browser stays open for 15 minutes.
3. Return to Composal, confirm I’m signed in to the correct test account, and choose Save Browser Session.

To paste cookies instead, choose Session cookies. Enter the App URL and paste one cookie per line as name=value or name:"value". A copied Cookie header also works. Choose Upload File Instead to upload a session file saved by the CLI.

To create your first credential from the CLI with a private cloud browser:

com verify browser-session --org your-org --project your-project \
  --url https://app.example.com/login --login --name "Test admin"

Complete sign-in in the viewer, then press Enter in the CLI to save. --name is optional; it defaults to the app hostname followed by “browser session”. Use --account vaccount_example instead to refresh an existing credential.

To capture a session from your own computer, use the CLI. It opens a fresh Chrome profile, waits for you to sign in, then uploads only that app's state:

com verify browser-session --org your-org --project your-project --account vaccount_example \
  --url https://app.example.com/login --local-login

Type save when the app shows the expected account. --chrome-profile Default imports from an existing Chrome profile instead, and --login opens a private cloud browser. Add --skip-indexed-db when your app's IndexedDB caches exceed the 1 MiB limit and authentication does not depend on them.

A session works only on the origin it was saved for. Runs against another origin, such as a pull request preview, fail preparation until you save a session for that origin.

Passkeys

Choose Passkey under More sign-in methods to upload an enrolled software passkey's private JSON file. Enroll the passkey yourself in your app's security settings: agents can sign in with it but cannot enroll new passkeys. The upload is valid for 30 days and works only on the origin it was enrolled for. A passkey signs in one run at a time. Some providers reject software authenticators, so test it with one run first.

Use credentials in runs

When you prepare a run, Verify picks each scenario's credential from the project, as described in how runs use credentials. To pin a credential to a persona, choose it as that persona's Credential.

Scenario steps use references to credential fields. When you edit a credential, Agent credential references lists keys such as VERIFY_…_USERNAME and VERIFY_…_PASSWORD. Bind project Personas to their configured Credentials; reference required credential fields in authored Scenario instructions. Managed-environment blueprints must also declare the keys each persona may use. Only the keys a run requests reach it.

Rotate, disable and remove

Organization administrators can edit a credential's guidance, rotate its password, and replace or remove its authenticator or browser session. Secret fields are write-only: leave them blank to keep the saved values. The username and guidance are visible metadata.

Disable blocks every value on the credential for future runs. It does not sign out a browser that is already signed in. Reconfiguring a disabled password credential requires a new password, and a disabled session or passkey requires a fresh file.

Delete permanently removes the credential and its saved secrets. If it has a Composal email address, its inbox and messages are also deleted, freeing the inbox slot. Past run reports remain available. Stop any runs or owner browsers using the credential before deleting it. If inbox cleanup is unavailable, the credential remains so you can retry.

Credential names are local labels: names such as Brand admin (prod) work with a Composal email address.

API and CLI

A project's credentials are available at /api/v1/organizations/{organization_id}/verification/projects/{project_id}/credentials: GET lists them, POST creates one, PATCH /{id} edits or rotates it, POST /{id}/disable disables it, and DELETE /{id}?permanent=true permanently deletes it and any Composal inbox. For older clients, DELETE without permanent=true still disables the credential. Writes accept the same fields as the form, plus passkey, browser_session or cookies for browser artifacts. Responses return metadata and credential references, never secret values. From the CLI, com verify admin --help lists the project credential commands; pass request bodies through a private --body-file or --body-stdin, never as arguments.

Next, see Better Auth sign-in for apps that can trust Composal directly.