Credential Templates

Credential templates let you define one shared credential identity for a property and connect it to the right test-user credentials in each environment. Use them to keep workflows portable so the same workflow can run in staging, production, sandboxes, and local environments without editing steps each time.

01When to use credential templates

Use credential templates when your workflows need the same kind of account in multiple environments, but the actual login details differ by environment. Instead of selecting a different credential in every workflow, you create one reusable template and map each environment to the correct credential.

Bootstrap-generated specs also use credential templates as logical credential identities. Release QA bootstrap can create generated coverage that refers to roles such as Admin user or Buyer account without binding those specs to one environment's saved credential. You review the generated workflows once, then map the template to the right saved credential in each environment where you want to run them.

Credential templates are most useful when you want to:

• Run the same workflow across staging, production, sandbox, and local setups
• Standardize shared test-user identities across a property
• Review and promote bootstrap-generated workflows before wiring in environment-specific credentials
• Reduce workflow maintenance when credentials change in one environment
• Avoid duplicating similar workflows just to swap test-user accounts

02Core concepts

Credential templates

A credential template is a top-level shared identity for a test user in a property. It represents the role or account type your workflow needs, such as Admin user, Buyer account, or Support agent, rather than a single environment-specific username and password.

Create credential templates when you want workflows to refer to a stable identity that stays consistent across environments. This gives you one place to manage how that identity maps to real credentials.

Environment-specific credential mappings

Each credential template can link to different saved credentials for different environments. These mappings let you keep one template name while attaching the correct environment-specific credential record behind it.

Use mappings to connect the template to the right test-user credential in each environment where the workflow can run.

Option	Description
Credential template	The shared identity your workflows reference
Environment mapping	The connection between the template and a saved credential for a specific environment
Saved credential	The actual environment-specific credential used to authenticate the test user

How workflows resolve credentials at runtime

When a workflow runs, Canary resolves the login step credential in this order:

1. Check whether the login step uses a scenario-provided credential input.
2. If the scenario provides a credential template, resolve that template against the selected run environment.
3. If the scenario provides a saved credential directly, use that credential for the run.
4. If the scenario does not provide a credential override, use the credential configured on the login step.
5. If the resolved value is a credential template, look for the mapping for the selected environment and use the linked saved credential.

This means a workflow scenario can provide or override the logical credential used by a login step without changing the workflow itself. Environment mappings still apply whenever the final resolved value is a credential template.

If no matching mapping exists for the selected environment, Canary cannot resolve that template for the run until you add one. Keep mappings complete for every environment type where you expect the workflow or scenario to run.

03Configuration

Creating a credential template

Create a credential template when you want a reusable test-user identity available across your property.

1. Open your property settings for test-user credentials.
2. Click New credential template.
3. Enter a clear template name that describes the shared identity, such as QA Admin or Standard Buyer.
4. Add any helpful context your team needs to recognize when to use this template.
5. Click Save.

Choose names based on the account role, not the environment. This keeps the template reusable when you add mappings for more environments later.

Linking environment credentials

After you create a template, link the saved credential for each environment where that identity exists.

1. Open the credential template.
2. In the environment mappings section, click Add mapping.
3. Select the environment.
4. Select the saved credential for that environment.
5. Click Save.

Repeat this process for each environment you want the template to support. Add mappings for staging, production, sandbox, or local environments as needed.

Editing and removing mappings

Update a mapping when the underlying test-user credential changes or when you need to point the template to a different saved credential in an environment.

1. Open the credential template.
2. Find the environment mapping you want to change.
3. Click Edit to select a different saved credential, or click Remove to delete the mapping.
4. Click Save to confirm your changes.

Removing a mapping stops workflows from resolving that template in the affected environment until you add a replacement. Review workflow coverage before removing mappings from active environments.

Using templates in workflows

You can select a credential template directly in a workflow login step. Use this when you want one workflow to log in as the same role across multiple environments without changing the step configuration for each run.

1. Open the workflow in the editor.
2. Select the login step.
3. In the credential selector, choose the credential template instead of a single saved credential.
4. Save the workflow.

At run time, Canary resolves the selected template against the run environment and uses the mapped saved credential for that environment.

If the selected environment does not have a mapping, Canary now surfaces a more actionable message so you can identify the missing environment setup and update the template before rerunning.

In ad hoc test setup, environment selection also handles template-backed credentials more clearly. When you switch between live and sandbox targets, review the selected credential template and confirm the target environment has a matching mapping.

Environment mapping and resolution

Use environment mappings to control which saved credential Canary uses for each environment. This lets the same login step work in staging, production, sandbox, or local environments as long as the template has a mapping for each one.

When you run a workflow with a scenario, the scenario can provide or override the credential used by the login step. If the scenario supplies a credential template, Canary still resolves that template by the selected environment for the run. If the scenario supplies a saved credential directly, Canary uses that saved credential and does not look up an environment mapping.

Sandbox-target setup follows the same environment-mapping rules. If your selected sandbox target uses a credential template, Canary resolves it against that sandbox environment. If the template is credential-producing, make sure the template can produce or reference the correct credential for the sandbox target you selected.

Run configuration	What Canary does
Login step or scenario resolves to a credential template, and the selected environment has a mapping	Uses the saved credential linked to the template for that environment
Login step or scenario resolves to a credential template, and the selected environment has no mapping	Shows a run setup message that identifies the missing environment mapping so you can update the template
Scenario provides a saved credential directly	Uses that saved credential for the run
Same workflow run in a different environment with a credential template	Resolves the same template again using that environment's mapping
Sandbox target uses a credential template	Resolves the template for the selected sandbox environment before the run starts

Review mappings whenever you add a new environment, create a new scenario, switch between live and sandbox targets, or want a workflow to run in a different environment type. Bootstrap-generated workflows follow the same pattern: bootstrap can create or rely on a logical credential identity first, and you complete the environment mappings later so the generated workflow can run where you need it. For more information about environments, see /docs/reference/environments.

04Best practices

• Name templates by user role or purpose, not by environment
• Add mappings for every environment where a workflow is expected to run
• Reuse templates across workflows to keep credential management centralized
• Let bootstrap-generated workflows keep logical credential identities so you can promote and reuse them across environments
• Bind environment-specific saved credentials after bootstrap review instead of editing each generated workflow separately
• Review mappings whenever you rotate or replace test-user credentials
• Keep template names simple and recognizable so authors can select the right identity quickly
• Verify environment coverage before running workflows in new or restricted environments

05Troubleshooting

If a workflow login step cannot use a credential template, check the template's environment mappings first. Confirm that the selected run environment has a saved credential mapped to the template.

If Canary shows a message that a credential template is not available for the selected environment, open the template and add or update the mapping for that environment. Then rerun the workflow or ad hoc test.

If you switch an ad hoc test between live and sandbox targets and the credential selection changes or becomes unavailable, confirm that the template supports the newly selected target environment. Sandbox targets resolve templates separately from live targets.

If you use a credential-producing template for sandbox setup, confirm that it is configured for the sandbox environment you selected and that the resulting credential is available before starting the run.

If you recently changed the underlying secret for a saved credential, reverify any affected login steps. Changing credential secrets clears previously verified login indicators until you verify the login again.

If a workflow works in one environment but fails in another, confirm that both environments are mapped on the same template and that each mapping points to the correct saved credential.

06Related

• Workflows
• Environments
• Release QA
• Test users
• Workflow runs