# Authentication

> Create an API key and send it as a bearer token.

Every request carries a secret API key in the `Authorization` header. A key belongs to one workspace and works only for that workspace. The same key works for the REST API and the [MCP server](https://tirver.com/help/mcp.md).

## Create a key

Only owners and admins can create keys.

1. Sign in to [app.tirver.com](https://app.tirver.com).
2. Open **Settings, API keys** and create a key.
3. Give it a name, choose its scopes and choose when it expires: 30 days, 90 days, 1 year or never. See [permissions](https://tirver.com/help/api/permissions.md).
4. Copy the key straight away. It is shown once. Afterwards only a short prefix, such as `trv_live_a1b2c3`, is shown so you can tell keys apart.

Tirver stores only a fingerprint of the key, so a lost key cannot be recovered. Create a new one and revoke the old one. Revoking takes effect at once. When you create a key, Tirver emails you a notice with the key name and the time, never the key itself.

## Send the key

Put the key in the `Authorization` header as a bearer token. Keys start with `trv_live_`.

**curl**

```bash
curl https://app.tirver.com/api/v1/workspace \
  -H "Authorization: Bearer $TIRVER_API_KEY"
```

**JavaScript**

```js
const headers = { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` };
const res = await fetch('https://app.tirver.com/api/v1/workspace', { headers });
```

**Python**

```python
headers = {"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"}
res = requests.get("https://app.tirver.com/api/v1/workspace", headers=headers, timeout=10)
```

`GET /api/v1/workspace` is a good first call: it needs a valid key but no scope, and it shows the name, prefix and scopes of the key you used.

A request with no key gets `401` with the code `missing_api_key`. An unknown, revoked or expired key gets `401` with `invalid_api_key`. A key without the scope an endpoint needs gets `403` with `insufficient_scope`. See [errors](https://tirver.com/help/api/errors.md).

## Keep keys safe

- Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
- Load keys from environment variables or a secret manager, not from source code.
- Use one key per integration, so you can revoke one without breaking the others.
- Give each key only the scopes it needs. Most reporting scripts need read scopes only.
- Set an expiry for keys that are only needed for a while, and revoke keys you no longer use. Revoke a key at once if you think it leaked.

## Not for the widget

The widget does not use API keys. It identifies customers with a hash signed by your identity secret. See [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md).

Source: https://tirver.com/help/api/authentication