Authentication

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.

Create a key

Only owners and admins can create keys.

1. Sign in to 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.
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 https://app.tirver.com/api/v1/workspace \
  -H "Authorization: Bearer $TIRVER_API_KEY"

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

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.

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.