Bind a secret to a test

Use a secret dependency when a script needs a credential such as an API key or a password. The value stays encrypted in the workspace vault. MaxoPerf decrypts it when a run starts and hands it to the runners as an environment variable. No page, API response or run view ever shows the value. To create and rotate secrets, see Secrets.

Bind a secret

1. Open the test and go to its Dependencies tab.
2. Click Add dependency and select the Secret kind.
3. Under Choose a secret, open the picker and select the secret from the vault. If it does not exist yet, click Add a secret at the foot of the picker. The vault opens in a new tab.
4. Optionally type a suffix under Env name. The field already shows the fixed SECRET_ prefix, and the hint underneath shows the exact variable. Leave the suffix empty to use the secret’s own name.
5. Click Add.

A secret named PAYMENTS_API_KEY with an empty suffix is injected as SECRET_PAYMENTS_API_KEY. A suffix of KEY gives SECRET_KEY. The console upper-cases the suffix and removes a SECRET_ you type yourself.

Read it like any environment variable:

const apiKey = process.env.SECRET_PAYMENTS_API_KEY;

Naming rules

• A name set through the console or the API must match ^SECRET_[A-Za-z0-9_]{1,120}$. The API answers 422 for any other name.
• Through the API you can leave the name out. The secret is then injected under its own name, with no SECRET_ prefix. The console always sends the prefixed name, so a secret bound there always starts with SECRET_.
• Bindings created before the prefix rule keep resolving under the name they were stored with.

What the run shows

A secret is never leased, so it does not appear in GET /v1/runs/<runId>/dependencies. The run’s Dependencies tab still lists the variable name in a row labeled Secret, with a note that only names are shown and values never are.

If a script prints a secret into an error message, the runner replaces it with [REDACTED]. The runner applies the same replacement to the values of every other injected dependency variable.

Rotate with confidence

Rotating a value takes effect on the next run, so a rotation can break a test that nobody has run since. Open Secrets in the workspace, click Used by on the secret’s row, and check which tests bind it and whether a run holds it right now. The same list is available as GET /v1/dependencies/usage?kind=secret&entityId=<secretId>.

Used by on a secret lists the tests that bind it, with no value shown.

Composite runs

When a master test and a member test both bind a secret under the same name, the member’s secret wins.

Next steps

• Secrets: create, rotate and delete vault entries.
• Run-time behavior: what the preparing phase does and what a run shows.
• Automate: the same binding through the API.