> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testorim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and API keys

> Minting a key, sending it, and what it can reach.

## Minting a key

API keys are created from the app, in
[Team settings](https://app.testorim.com/settings/team), and only from a
signed-in browser session. A key cannot mint another key.

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.

Keys can be given an expiry, and can be revoked at any time.

## Sending it

An HTTP Bearer token on the `Authorization` header:

```bash theme={null}
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.

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  - name: Smoke test
    env:
      TESTORIM_API_KEY: ${{ secrets.TESTORIM_API_KEY }}
    run: npx @testorim/cli run <procedure-id>
  ```

  ```bash curl theme={null}
  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 '{"procedureId":"<procedure-id>"}'
  ```
</CodeGroup>

## What a key can reach

A key is bound to one person and one workspace, and inherits that person's
role there.

|                |                                                                          |
| -------------- | ------------------------------------------------------------------------ |
| **Scope**      | The one workspace it was issued for. Resources elsewhere return `404`.   |
| **Role**       | `viewer` keys are read-only and get `403` `read_only_role` on any write. |
| **Revocation** | Immediate. Also stops working if the person leaves the workspace.        |
| **Expiry**     | Optional, set at creation.                                               |

## Checking a key

```bash theme={null}
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.

## 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.


## Related topics

- [API reference](/api-reference/introduction.md)
- [Revoke an API key](/api-reference/api-keys/revoke-an-api-key.md)
- [List active API keys](/api-reference/api-keys/list-active-api-keys.md)
- [Mint a new API key (browser session only)](/api-reference/api-keys/mint-a-new-api-key-browser-session-only.md)
- [Identify the presented credential](/api-reference/identity/identify-the-presented-credential.md)