Credentials and Login

01Add credentials

• Add credentials on the property.
• Validate login using the preview tools before running large crawls/runs.
• Review where a credential is used before you delete it so you do not break existing automations.

You can create credentials directly on the property or let a sandbox action create or update a credential from action output. Use sandbox-generated credentials when you need to provision an account, token, or other secret inside a sandbox and reuse it in later workflows.

When you add a credential, review the context Canary shows for it after save. The credential details can show where the credential came from, whether it is ephemeral, whether login has been verified, which environments or runs it is tied to, and whether Auth Handoff is configured. Use that context to decide whether the credential is ready for repeat use or should stay limited to a specific run or environment.

You can also create credential templates for test users. A credential template gives you one shared identity for a property, then lets you link a different credential to that identity for each environment. Use this when the same workflow needs to sign in as the same kind of user across staging, production, sandboxes, or local environments without changing the workflow itself.

When a sandbox action creates or updates a credential, Canary stores it as a first-class credential on the property. You can then select and manage it like any other credential in later runs.

If a credential is marked as ephemeral, treat it as temporary. Ephemeral credentials usually come from a specific run, setup flow, or short-lived provisioning step. Revalidate them before you depend on them in recurring workflows, and replace them with a stable property credential when you need long-term reuse.

You can now pair a provisioned inbox email with any credential. Use this when your test account needs email access for sign-in codes, password resets, invitations, or other messages, even if the credential itself logs in with a username or another non-email identifier.

Provision an inbox when the account under test must receive email during setup or login. Skip inbox provisioning when the account never needs email and the credential only requires a username, password, token, or cookie.

You can also add credentials to reusable scenarios. Add a credential input to the scenario when the same workflow needs to run as different accounts. Then point the workflow's Login step at that scenario credential input so each saved scenario can supply its own account without changing the workflow.

Use reusable scenario credentials when you want to:

• Keep one workflow and swap accounts by scenario
• Save role-based variations such as buyer, admin, or support-agent
• Avoid editing login steps every time you test a different account
• Reuse the same scenario in suites and manual runs

1. Open your property credentials.
2. Create a new credential or open an existing one.
3. Add the login details the credential needs.
4. If the credential should forward browser-based authentication into API requests, open Auth Handoff and choose what saved session state Canary should reuse.
5. Review the Auth Handoff setup so the credential forwards the right browser-backed auth into downstream API requests.
6. If you switch the login source or login method while editing, review the form before you save. Canary now clears stale values more reliably when you change sources, so expect fields from the previous selection to be removed instead of carried forward.
7. Choose to provision an inbox if the account needs to receive email.
8. Save the credential.
9. Review the saved credential status, source, inbox badge, verification state, and Auth Handoff status before you use it in a workflow.
10. If the credential will be selected through a scenario, add it to the scenario's credential inputs before you run the workflow or suite.

After you pair an inbox, Canary shows the provisioned inbox email on the credential so you can confirm which mailbox belongs to that account. The credentials list also shows an Email inbox badge so you can quickly see which credentials are ready for email-based login or verification flows without opening each credential.

If you configure Auth Handoff, Canary can reuse authentication captured from a saved browser session for downstream API requests that use the same credential. Use this when your app signs in through the browser but your API tests need the resulting cookies or tokens without recreating them manually.

Expect Auth Handoff to work best when the saved session already contains the authentication state your API depends on. Review and refresh the saved session if your app rotates tokens frequently or only issues them after a later in-app action.

If you no longer need the inbox on that credential, remove the paired inbox from the credential settings. Removing the paired inbox only detaches the mailbox from that credential. Review any workflows that depend on emailed codes or links before you remove it.

If you no longer need a credential profile, start the delete action and review the confirmation step before you remove it. The confirmation step lists the flows that currently use the credential so you can update those flows first or keep the credential in place.

To avoid breaking existing automations:

1. Open your property credentials.
2. Select the credential you want to remove.
3. Start the delete action.
4. Review the confirmation step and check which flows use the credential.
5. Update those flows to use a different credential, or remove the credential only after those flows no longer depend on it.

02API login

Use API login when your application authenticates with an HTTP request instead of an interactive login form. Configure the login request, then map the authentication value from the response into your credential.

You can now capture authentication values from either the JSON response body or a Set-Cookie response header. Use cookie-based capture when your login endpoint returns the session token or auth cookie in a response header instead of in the body.

1. Open your property credentials.
2. Choose API login.
3. Enter the login endpoint and request details.
4. Select where to read the authentication value from:
   • JSON response body for APIs that return a token in the response payload
   • Set-Cookie header for APIs that return the auth value as a cookie
5. Validate the result with the preview tools.
6. Save the credential.

03Credential configuration

Use the source that matches your login response.

Option	Use when	Notes
JSON response body	The login endpoint returns the auth value in the response payload.	Map the token from the expected response field.
Set-Cookie header	The login endpoint sets the auth value in a cookie.	Use this when the response body does not include the auth value you need.

When you use Set-Cookie header, make sure the login preview shows the expected cookie after the request completes. If your endpoint sets multiple cookies, confirm you are capturing the cookie used for authenticated requests.

If JSON body capture is already working for your login flow, keep that configuration. Switch to Set-Cookie header only when your authentication flow depends on cookies returned in the response headers.

04Authenticate Canary so it can test logged-in areas of your app

Use a Login step when your workflow needs Canary to authenticate before testing protected pages. Choose the login behavior that matches how you want the workflow to start each run.

Note: A Login step can now pull credentials from scenario credential inputs. Use this when you want one workflow to run against different accounts without editing or rebuilding the workflow.

Setting	Use when	What happens
Log in with credential	You want the workflow to perform a fresh login with a selected credential, credential template, or scenario credential input.	Canary runs the login step with the credential source you choose for that workflow or scenario.
Reuse existing session	You already have a valid authenticated session from an earlier setup flow or seed workflow.	Canary keeps using that session instead of logging in again at the start of the step.

Sandbox-generated credentials are available in later workflows after the sandbox action saves or updates them. Use this when one workflow provisions an account or secret in a sandbox, then a follow-up workflow needs to log in with the same credential.

Credential templates for test users make workflow setup easier across environments. Select the shared test-user identity in the Login step, then let Canary use the environment-specific credential linked to that identity at run time.

Scenario credential inputs make one workflow more reusable across accounts. Add a credential input to the workflow scenario, then configure the Login step to use that scenario input. At run time, select a saved scenario or override the credential input so the same workflow can log in as a different account.

Choose a direct credential when the workflow should always log in with one specific account, such as a single staging-only admin user or a credential produced by a setup flow. Choose a credential template when the workflow should keep the same user role across environments and resolve the correct environment-specific credential at run time. Choose a scenario credential input when the account should change per scenario or per run without changing the workflow itself.

Use a direct credential when you want to:

• Pin the workflow to one exact account
• Reuse a credential created by a sandbox action or setup flow
• Test a single environment without maintaining template mappings

Use a credential template when you want to:

• Reuse one workflow across staging, production, sandboxes, or local environments
• Keep role-based identities like buyer, admin, or support-agent consistent
• Manage usernames, passwords, or tokens separately for each environment without editing the workflow

Use a scenario credential input when you want to:

• Run the same workflow against different saved accounts
• Switch accounts by selecting a different scenario before launch
• Override the account for one run without editing the workflow
• Combine reusable scenarios with workflow login configuration

When you use scenarios in suites, Canary fans out the workflow across the saved scenarios that are enabled for suite execution. Keep the credential input on each scenario current so each variation logs in with the intended account.

If your workflow signs in as more than one user, add a separate Login step each time you intentionally switch accounts. Select the credential, credential template, or scenario credential input for the next user instead of relying on a previous session to change users. This makes account transitions more predictable during a run.

When you switch users in one workflow, prefer Log in with credential for the step that starts the new user session. Use Reuse existing session only when the earlier step already established the exact session you want to continue using.

When you use API-sequence tests or other API requests after a browser login, configure Auth Handoff on the credential you use for that login. This lets Canary forward saved browser authentication into downstream API requests instead of requiring you to recreate headers or cookies by hand.

Use Auth Handoff when you want to:

• Reuse cookies captured during a browser session in API requests
• Forward tokens stored in localStorage to downstream API tests
• Reuse auth values stored in IndexedDB for apps that keep tokens outside cookies
• Support browser login flows that refresh tokens in the background before API calls run

Saved sessions can provide downstream API auth only when the browser session contains the auth data your application actually uses. If the app does not populate the needed cookie or token until after a later interaction, complete that interaction before you save or validate the session.

Expect refresh-token-based flows to depend on a live browser-backed session. If your app renews access tokens behind the scenes, keep using the same saved browser session so Canary can pick up the current auth state for API requests.

When you change the selected credential source in a Login step, review the fields before you save. Canary now clears stale values more reliably when you switch sources, so expect inputs from the previous source selection to disappear instead of staying in place.

If your login flow sends a code or link by email, select a credential with a paired inbox. The inbox can belong to any credential type, including credentials that sign in with a username instead of an email address. Treat the Email inbox badge in the credentials list as a quick readiness signal for these flows.

05Test users

Use test users when you want one workflow to represent the same user role across multiple environments. A test user is a shared identity, such as buyer, admin, or support-agent, that points to a different saved credential in each environment.

This lets you build the workflow once and keep the selected identity consistent. Canary resolves that shared identity to the correct environment-specific credential when the workflow runs.

Test user identity	Example environment mapping
buyer	Staging buyer credential, production buyer credential, sandbox buyer credential
admin	Staging admin credential, production admin credential, local admin credential
support-agent	Sandbox support credential, QA support credential, production support credential

Use credential templates for test users when you want to:

• Reuse the same workflow in more than one environment type
• Avoid editing workflow login steps every time you switch environments
• Keep role-based identities consistent across your property
• Manage environment-specific usernames, passwords, or tokens separately

When you configure a workflow to log in with a test user template, select the shared identity instead of selecting a single environment-bound credential. Keep each environment mapping up to date so the workflow can resolve the correct credential during the run.

During suite execution, expect Canary to prepare saved credentials ahead of the workflow steps that need them. Your workflow should still include the correct Login step configuration, but you should see fewer cases where the beginning of a suite run is delayed by session setup.

Use Reuse existing session only when a previous part of the workflow has already established the session you want to keep. If no authenticated session exists, Canary cannot use this option to create one.

If your workflow starts from a seed workflow, review which credentials are already available before you configure the Login step. Canary can use credentials inherited from the seed workflow, so you may not need to create or select a new credential again.

To configure login for a workflow:

1. Open the workflow where you want to test logged-in areas.
2. Add or edit the Login step.
3. Choose whether to Log in with credential or Reuse existing session.
4. If you choose Log in with credential, select the credential source the workflow should use.
5. Use a direct credential for one fixed account, use a credential template to resolve the right account per environment, or use a scenario credential input to supply the account from the selected scenario.
6. If the workflow will run API requests that depend on browser-based auth, confirm the selected credential has Auth Handoff configured.
7. If you switch from one credential source type to another while editing, review the step before you save. Canary now clears stale values more reliably, so the new source should not keep values from the previous selection.
8. If you need to switch to a different user later in the workflow, add another Login step and select the next credential source for that user.
9. If the login flow needs email verification, password reset messages, or invite links, confirm the selected credential has a paired inbox or shows the Email inbox badge in the credentials list.
10. If you use a credential template, confirm the selected environments have a linked credential for that identity.
11. If you use a scenario credential input, confirm the selected scenario includes the credential you expect before you run the workflow.
12. If the credential was created or updated by a sandbox action, confirm it contains the account or secret you expect before you run the workflow.
13. If the workflow starts from a seed workflow, confirm whether the needed credential is inherited.
14. Save the step and run the workflow to confirm Canary reaches the authenticated area.

If the workflow unexpectedly starts logged out, confirm the session is created before you choose Reuse existing session. If the wrong account is used, review the selected direct credential, credential template mapping, or scenario credential input value and update the run configuration before launching again.

If you reauthenticate in the middle of a workflow, expect Canary to replace the earlier login state with the new one from that step. If you want to keep testing as the original user later, add another Login step and sign back in with that original credential.

For login testing, Canary now preserves a single reusable demo Login workflow at the organization level when possible. This helps you keep a stable example of a successful login flow without creating a new demo artifact every time you validate credentials.

Expect login validation to reuse that existing demo workflow instead of creating duplicates. If you rerun login testing for the same organization, review the updated demo workflow result rather than looking for a newly created copy.

For suite runs, if the workflow starts authenticated sooner than before, that is expected. Warmed credentials help Canary reach a ready session state before the main workflow steps begin, but they do not replace your workflow's login settings or fix an invalid credential.

If a stale session could affect your workflow, prefer adding an explicit Login step near the point where authenticated work begins. This keeps the run anchored to the credential you selected instead of depending on leftover authentication state from an earlier step.

06Environment-specific behavior

Credential templates for test users affect how workflows run across environments.

Situation	What happens
The selected environment has a linked credential for the test user identity.	Canary uses that environment-specific credential for the login step.
The selected environment does not have a linked credential for the test user identity.	The workflow cannot use that test user in that environment until you add a mapping.
A workflow is limited to certain environment types.	Canary shows the environment eligibility and explains when a workflow is skipped because the selected environment is not eligible.
You run the same workflow in staging and production.	Canary keeps the same test user identity in the workflow but swaps to the mapped credential for each environment.

Review environment mappings whenever you add a new environment or duplicate an existing one. If a test user template is missing a credential for that environment, login-dependent workflows may not run as expected.

If your team uses workflow environment constraints, check those settings alongside your test user mappings. A valid credential mapping does not override workflow eligibility rules for environment type.

07Managing credentials

Use the property credentials list to understand not just what a credential contains, but whether it is ready to use.

The updated credential rows can show source, verification status, linked environments, whether a credential is ephemeral, whether it has a paired inbox, and whether Auth Handoff is enabled. Use these details to quickly find stable credentials for shared workflows and isolate temporary credentials that came from a single run or setup path.

Use the surfaced credential context this way:

Credential detail	What it tells you	What to do
Source	Where the credential came from, such as a direct property credential or a credential created from a run or sandbox flow.	Confirm the credential comes from the workflow or setup path you expect before you reuse it.
Verified login	Whether Canary recently confirmed the credential can authenticate successfully.	Prefer verified credentials for recurring workflows. Revalidate credentials that are unverified or failing.
Email inbox	Whether the credential has a paired inbox available for email-based flows.	Prefer credentials with this badge when login requires emailed codes, links, invites, or password resets.
Auth Handoff	Whether the credential is set up to forward browser-based authentication into API requests.	Enable this when browser login state should power downstream API tests. Review it when API requests stop inheriting browser auth.
Ephemeral	Whether the credential is temporary instead of intended for long-term property use.	Replace ephemeral credentials with a stable saved credential when the workflow needs repeated use.
Linked environments	Which environments currently map to a credential or test user identity.	Check mappings before you run a workflow in a different environment.
Run context	Which run created or used the credential most recently.	Use this to trace a credential back to the workflow run that provisioned or validated it.

When you manage credentials on a property, review these states before you edit, reuse, or delete anything. This is especially important when multiple teams share the same property and some credentials are created automatically during setup flows.

If a credential shows as verified, you can usually reuse it with more confidence. If it is not verified, validate login again before you attach it to a scheduled workflow or suite.

If a credential shows the Email inbox badge, you can use it for flows that depend on email delivery. If the badge is missing, Canary can still use the credential for non-email login paths, but email verification steps, magic links, invitations, or reset flows may fail.

If a credential shows Auth Handoff as configured, you can use that credential in browser and API test paths that share the same saved login state. If downstream API auth starts failing, refresh the saved browser session and confirm the credential still captures the auth data your app uses.

If you update a credential's secret, password, token, or other login value, expect Canary to clear any previous verified login marker. Validate the updated credential again before you rely on it in a workflow or suite.

When you edit saved login details or switch a credential to a different login source, review the form before you save. Canary now clears stale values more reliably, so fields from the previous source should no longer remain in the updated credential.

If a credential is linked to environments through a test user identity, update those mappings in the template instead of creating duplicate environment-specific workflows. If a credential appears only in run context and is marked ephemeral, keep it scoped to that use case unless you intentionally promote it to a longer-lived property credential.

08Troubleshooting

• If validation fails, confirm the login endpoint returns the auth value in the source you selected.
• If you use Set-Cookie header, verify the cookie is present in the preview response headers.
• If your endpoint returns multiple cookies, check that the authentication cookie is the one used by your application after login.
• Re-run the preview tools after each change so you can confirm the credential captures the correct value before saving.
• If a credential shows as unverified, validate it again before you use it in a workflow or suite.
• If a credential shows as unverified right after you update its secret, that is expected. Canary clears the previous verification marker when the login secret changes.
• If a credential was created from a run or sandbox flow, review its source and run context to confirm you are using the correct account or secret.
• If an ephemeral credential stops working, recreate it from the original setup flow or replace it with a stable saved credential.
• If you switch login sources while editing a credential and values disappear, that can be expected. Canary now clears stale values more reliably so the form matches the source you currently selected.
• If old values still appear after you switch login sources, reselect the source once, then review the remaining fields before you save.
• If an authenticated replay fails after the credential was recently updated, rerun the workflow so Canary can use the latest saved credential instead of an older session state.
• If an authenticated run fails after a long idle period, run the workflow again with an explicit Login step so Canary can refresh the session at the point where authenticated work begins.
• If an automated suite run still starts logged out, confirm the saved credential is still valid and that the workflow uses the expected Login step setting.
• If suite behavior changes between runs, confirm the credential has not expired or been replaced with a different account.
• If you use reusable scenarios, open the selected scenario and confirm its credential input still points to a valid saved credential.
• If a scenario-based run starts with the wrong account, confirm the selected scenario, overridden credential input, and Login step all point to the same intended user.
• If you use Reuse existing session, remember that warmed credentials do not create a session for that option. Make sure an earlier step or seed workflow has already established the session you want to keep.
• If a workflow fails after switching users, add an explicit Login step for the second user instead of relying on the earlier session to change accounts.
• If a workflow reauthenticates but still behaves like the previous user, rerun the workflow with an explicit Login step for the intended account at the point where that account should take over.
• If you changed the credential source in a Login step and the workflow now uses the wrong account, reopen the step and confirm the current source selection and saved fields match each other.
• If a workflow fails only in one environment, confirm the selected credential template has a linked credential for that environment.
• If the wrong user logs in, review the environment-specific credential mapped to the shared credential template identity.
• If the wrong user logs in when you use a scenario, open the selected scenario and confirm the credential input points to the expected account.
• If a workflow runs with a missing login credential, confirm the selected scenario includes a value for the credential input or override that input before launch.
• If your login flow waits for an email that never arrives, confirm the credential has a paired inbox or shows the Email inbox badge in the credentials list.
• If a username-based login cannot complete email verification, provision and pair an inbox even though the username itself is not an email address.
• If you rerun login validation and do not see a new demo Login workflow, that can be expected. Canary can reuse the existing organization-level demo workflow instead of creating another artifact.
• If you removed a paired inbox and login started failing, reattach or reprovision the inbox on that credential before rerunning the workflow.
• If login behavior changes after a long idle period, rerun the workflow with an explicit Login step to refresh authentication state instead of relying on an older session.
• If downstream API requests start failing after a browser login, confirm the credential has Auth Handoff enabled and that the saved session still contains the needed cookie or token.
• If your API test does not inherit browser auth, refresh the saved session and confirm your app stores the auth value in cookies, localStorage, or IndexedDB during the browser flow.
• If a refresh-token-based app works in the browser but fails in API tests, reuse the same browser-backed session and rerun after the app has completed its normal token refresh.

09Security

• Treat credentials as secrets.
• Prefer service accounts with least privilege.
• Do not delete a credential until you confirm which flows use it.
• Replace credentials in dependent flows before you remove an existing credential profile.
• Review sandbox-generated credentials before you reuse them in other workflows.
• Remove or rotate sandbox-generated credentials when the sandbox account, token, or secret is no longer trusted.
• Treat ephemeral credentials as short-lived access and remove or replace them when they are no longer needed.
• Verify login before you attach a credential to scheduled workflows, suites, or shared test user mappings.
• Confirm linked environments before you reuse a credential across staging, production, sandboxes, or local environments.
• Provision inboxes only for credentials that need to receive email during setup or login.
• Treat a paired inbox as part of the credential's access path, especially for verification-code, magic-link, invitation, and password-reset flows.
• Remove a paired inbox from a credential when the mailbox is no longer needed.
• Treat Auth Handoff as an extension of the credential's access path because it can forward browser-derived cookies and tokens into API requests.
• Revalidate saved sessions used for Auth Handoff when your app rotates auth state frequently or refreshes tokens in the background.
• Review which browser storage sources your app uses for auth before you rely on saved session state in API tests.
• Reuse the organization-level demo Login workflow only as a validation artifact. Do not treat it as a replacement for reviewing and maintaining the real workflows that depend on the credential.

Sandbox-generated credentials let you reuse values produced inside a sandbox, but you should only reuse credentials that come from sandbox actions you trust. If a sandbox action provisions a temporary account or short-lived secret, plan to rotate or delete that credential when it is no longer valid.

If a credential shows source or run context from a one-off setup flow, review that context before promoting it to broader use. This helps you avoid turning temporary setup access into a long-lived shared credential without review.

If you use Auth Handoff, remember that browser-derived auth can include cookies and tokens from the saved session state. Keep that credential scoped to the environments and workflows that actually need it, and remove or refresh it when the stored auth state is no longer trusted.

If your application stores auth in localStorage, IndexedDB, or a refresh-token-backed browser session, review who can reuse that credential and where it runs. Limit access to the smallest set of teams, workflows, and environments that need that authenticated state.

If you need to rotate or remove a credential, check the deletion confirmation step first. Use that flow list to identify impacted automations, move them to another credential, and then complete the deletion only when it is safe to do so.

If you pair an inbox with a credential, treat that inbox as part of the account's access path. Remove the pairing when you no longer need Canary to read email for that account, especially for temporary users or one-time onboarding flows.

10Related

• /docs/reference/workflows
• /docs/reference/test-runs
• /docs/reference/environments
• /docs/reference/credentials-and-login