Authentication and API keys

Minting a key

API keys are created in the app, under Settings → API keys, from a signed-in browser session. Every workspace can have keys, personal workspaces included. A key cannot mint another key. A key belongs to the workspace you are in when you create it, and it only ever acts there. The key list names the workspace each key runs in. The token is shown once, at creation. It is stored as a SHA-256 hash, so nobody, including us, can recover it later. Lose it and you revoke it and mint a new one. A key can expire in 30 days, 90 days or a year, or never, and can be revoked at any time.

Sending it

An HTTP Bearer token on the Authorization header:

curl https://app.testorim.com/api/me \
  -H "Authorization: Bearer tst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Keys carry the literal prefix tst_live_. There is no custom header. The Authorization header is the only one read, and it accepts either an API key or a browser session token.

In CI

Store the key as a secret and pass it through the environment. Never commit it.

- name: Smoke test
  env:
    TESTORIM_API_KEY: ${{ secrets.TESTORIM_API_KEY }}
  run: npx @testorim/cli run <procedure-id>

export TESTORIM_API_KEY="tst_live_…"
curl -X POST https://app.testorim.com/api/runs/trigger \
  -H "Authorization: Bearer $TESTORIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>","procedureId":"<procedure-id>"}'

What a key can reach

A key is bound to one person and one workspace, and inherits that person’s role there. It is a CI credential, not a stand-in for the person: it can read what they can read in that workspace, and make only a short list of changes.


Workspace	The one it was created in. Resources elsewhere return `404`, including a route that names another workspace.
Reads	Anything its owner can read in that workspace.
Changes	Trigger a run, cancel a run or a batch, create a project, revoke a key. Anything else, such as billing, people, settings or integrations, answers `403` with `code: "api_key_scope"`.
Role	A `viewer`’s key is read-only and gets `403` `read_only_role` on any change.
Revocation	Immediate. A key also stops working if its owner leaves the workspace.
Expiry	Optional, set at creation.

Checking a key

curl https://app.testorim.com/api/me -H "Authorization: Bearer $TESTORIM_API_KEY"

200 tells you who the key belongs to and which workspace it is pinned to. 401 means the key is wrong, revoked, expired, or its owner has left. Five failed attempts in 15 minutes from one address turn into 429.

Good hygiene

One key per pipeline, so revoking one does not break the others.
Set an expiry on anything short-lived.
Revoke rather than rotating in place, because revocation is immediate.
Never put a key in a base URL, a query string or a log line.

​Minting a key

​Sending it

​In CI

​What a key can reach

​Checking a key

​Good hygiene