> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tester.army/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tester.army/_mcp/server.

# Test Credentials

> Save encrypted login credentials per project so the AI agent authenticates automatically during test runs, with multiple roles, OAuth, MFA (TOTP), and environment overrides.

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](/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](/auth/credentials) or [SMS phone number](/auth/sms-phone-numbers) instead.

## Environment overrides

If the same account role uses different login details on staging, preview, or another saved [environment](/guides/environments), 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.