API keys

Create, list and revoke keys in the app, under API keys.

The shape of a key

plx_<id>_<secret>

The plaintext is shown exactly once, at creation. Evalwright stores only a hash of it, so a key that was not copied cannot be recovered — create another one and revoke the first.

Scopes

A key is either scoped to the whole organization (*) or to an explicit list of prompt ids. Use the list whenever the key leaves your own backend: a scoped key used against a prompt outside its list is refused with 401, so the blast radius of a leaked key is the prompts you chose rather than everything the organization owns.

Where to put it

The key is a bearer credential: anything holding it can resolve the prompts it is scoped to. Keep it on the server.

• In a secret store (Secret Manager, Vault, your platform's own), read into the process at startup.
• Never in frontend code. A key in a bundle is a key you have published.
• Never in the repository. Committed keys are found automatically, and the clean-up is a rotation rather than a delete.

const client = new EvalwrightClient({
  apiKey: process.env.EVALWRIGHT_API_KEY!,
  baseUrl: process.env.EVALWRIGHT_BASE_URL!,
});

Rotation

Create the new key, deploy it, then revoke the old one. Revocation takes effect on the next request — there is no grace period, which is what you want the day a key leaks and not what you want in the middle of a deploy.

Each key records when it was last used, so a key nothing touches is safe to revoke.