Credential Templates

A persona is a shared test-user identity for an application — a role like Admin user, Buyer account, or Support agent — rather than one environment-specific login. You map the persona to a real credential in each environment, then reference the persona in your flows. The same flow runs in staging, production, sandboxes, and local without editing its login steps.

Personas were previously called credential templates; the CLI keeps canary credential-template as an alias.

01When to use a persona

Reach for a persona when a flow needs the same kind of account in multiple environments but the actual logins differ. Instead of selecting a different credential per environment, you create one persona and map each environment to its credential. Personas are useful to:

• Run one flow across staging, production, sandbox, and local
• Standardize shared test-user identities for an application
• Cut maintenance when a credential changes in a single environment
• Avoid duplicating flows just to swap accounts

02How it fits together

On a static environment (staging, production, local), a persona has one saved mapping per environment. At run time, when a login step (or scenario) resolves to a persona, Cofactor looks up the mapping for the selected environment and uses the linked credential. A scenario can also supply a credential directly, in which case no mapping lookup happens.

If the selected static environment has no mapping, Cofactor can't resolve the persona and surfaces an actionable message — add the mapping, then rerun.

On a sandbox, personas resolve differently — there's no static mapping to add, because the users don't exist until an instance is running. See Personas on sandboxes below.

03Create and map a persona

1. Open your application's Test Users tab and click New persona.
2. Name it by role, not environment (QA Admin, Standard Buyer), and add any context your team needs.
3. Save, then add a mapping per environment: choose the environment and the saved credential for it. Repeat for each environment you want to support.

Editing a mapping points the persona at a different credential; removing one stops flows from resolving the persona in that environment until you replace it.

04Use a persona in a flow

Select the persona in a Login node instead of a single credential. At run time Cofactor resolves it against the run environment and uses the mapped credential — so one login step works everywhere the persona is mapped. Sandbox targets resolve the same persona too, but through a provisioning action rather than a static mapping — see Personas on sandboxes.

05Personas on sandboxes

A sandbox starts empty — the users a persona maps to don't exist yet — so there's nothing to pre-map. Instead of a static credential mapping, you bind a credential-provisioning action to the persona on the sandbox template. When a flow logs in as that persona against the sandbox, Cofactor runs that action on the live instance to create the user and register the login, then resolves the flow's login to it.

A few things follow from this:

• You don't add a per-environment mapping for a sandbox. Binding the provisioning action to the persona is the equivalent step. The setup guide shows how.
• The credential is minted on the running instance, not on the durable sandbox-environment pointer. The same persona still works unchanged across staging, production, and a freshly provisioned sandbox.
• Point the flow's default at the sandbox environment, not at a specific instance's ephemeral environment — ephemeral environments are transient and can't be set as a default. The sandbox environment resolves to a live instance at run time.
• A live instance is required. If none is running when the flow starts, the run provisions one first. If a persona login fails to resolve on a sandbox, the usual cause is that no instance was live, or that no provisioning action is bound to that persona — not a missing mapping. Warming the template first (cofactor sandbox warm <template-id> --wait) avoids the cold start.

See Sandboxes → Personas on a sandbox for the full picture.

06Best practices

• Name by role or purpose, never by environment.
• Add a mapping for every environment a flow is expected to run in.
• Reuse personas across flows to keep credential management in one place.
• Review mappings whenever you rotate credentials, add an environment, or switch a flow between live and sandbox targets.
• After rotating a credential's secret, re-verify the affected login steps — changing a secret clears the verified-login indicator.

07Related

• Credentials
• Applications
• Core nodes
• Scenarios