Test Credentials

Save login credentials in your project so the AI agent can authenticate automatically during test runs. No passwords in test prompts.

Adding credentials

1. Go to Project → Test Accounts
2. Click Add Credential
3. Choose an auth method and fill in the required fields:
   • Label - identifies the credential (e.g., “admin”, “viewer”)
   • When to use - optional description the AI agent reads when choosing between credentials (see below)
   • Username - email or username
   • Password - stored encrypted
   • Authenticator secret - optional, for accounts behind authenticator-app MFA
   • Login instructions - required only for custom auth
4. Click Save

You can add multiple credentials per project for different roles (admin, regular user, read-only viewer, etc.). You can also add credentials for Google and GitHub OAuth flows.

Limits

• A project can store up to 50 credentials. Past that, adding another one fails until you delete some.
• Each run passes at most 20 credentials to the agent. Every credential in that list is read before the agent’s first action, so large lists slow runs down and make account selection unreliable. When a project has more than 20, the run keeps every credential selected on a login step and fills the rest of the list with the most recently created ones.

If a test needs a specific account, select it on the login step. Pinned credentials are always available to the agent, regardless of how many the project stores.

Telling the agent when to use each credential

When a project has several credentials, dynamic PR runs pick which account to sign in with. The When to use description is the strongest signal for that choice: use it to document the account’s type, which features or plans are enabled on it, and which environments it exists in.

Good descriptions look like:

• “Admin account on the premium plan with all feature flags enabled. Exists on production and every preview database.”
• “Free-tier account - use for signup, billing, and plan-upgrade flows only.”
• “Only exists on the main staging database; preview databases do not have this account.”

Without descriptions, the agent falls back to matching labels against the target environment and the PR topic, which cannot know that an account lacks a feature or is missing from an isolated preview database.

If a saved credential is missing or rejected during a run, see Auth Troubleshooting.

MFA / authenticator codes (TOTP)

If the test account requires a one-time code from an authenticator app (Google Authenticator, 1Password, Authy, etc.), save its authenticator secret on the credential. This is the base32 setup key shown during MFA enrollment - usually behind a “can’t scan the QR code?” link - and pasting the full otpauth:// URI from the QR code also works.

During runs the agent generates a fresh 6-digit code from the secret at the moment it fills the MFA prompt, the same way a password manager does. The secret is stored encrypted like a password, and neither the secret nor the generated codes are exposed to the AI model or shown in run transcripts.

To stop generating codes for a credential, edit it and click Remove next to the authenticator secret, then save.

For email or SMS one-time codes (rather than authenticator apps), use a saved inbox or SMS phone number instead.

Environment overrides

If the same account role uses different login details on staging, preview, or another saved environment, edit the credential and add an environment override. The test still references the same credential, such as “admin”, but TesterArmy automatically uses the environment-specific username, password, or custom instructions for runs targeting that environment.

Production uses the default credential and does not support environment overrides.

Leave override fields blank to inherit the default credential. Clear an override to return that environment to the default values.

Webhook and API-triggered runs must pass projectEnvironmentId for these overrides to apply. Copy the environment ID from Project Settings → Test environments, or read it from GET /api/v1/projects/{projectId}. Passing only environment: "staging" changes the Results label, but it does not select saved environment credentials.

Custom auth

Use Custom when your app has an auth flow TesterArmy does not handle directly, such as:

• A staging bypass link or test-only route
• Unsupported SSO
• An extra access-code step before the normal login form
• A multi-step flow that needs app-specific instructions

Write clear login instructions for the agent, for example: “Open /staging-login, click the test-only bypass link, enter the access code shown on the page, then continue to the dashboard.”

Custom instructions are encrypted at rest, but they are sent to the AI agent during a run and may appear in run traces and logs. Use the username/password auth method when you need to store reusable login secrets, and never put production credentials in custom instructions.