---
title: "Authentication"
description: "Bearer keys, scopes, expiry, revocation and rotation without downtime."
url: https://developer.tendralhealth.com/docs/authentication
---

# Authentication

Authenticated endpoints take an API key as a bearer token. A key belongs to one organization, carries scopes, and can be rotated without downtime.

## Send the key

```http Header
Authorization: Bearer tk_live_…
```

A request with no key, a malformed key, or a revoked or expired key gets `401` with code [`UNAUTHORIZED`](/docs/errors#UNAUTHORIZED). The answer is the same in every case, so it says nothing about which keys exist.

## Key format and storage

Every key starts with `tk_live_` followed by 64 hex characters (256 random bits). You see a key once, when it is issued. Tendral stores only its SHA-256 hash, so a lost key cannot be shown again: ask for a new one and revoke the old.

## Scopes

A key is limited to the scopes it was issued with. Each endpoint in the [API reference](/reference) names the scope it needs. A call outside the key's scopes gets `403` with code [`INSUFFICIENT_SCOPE`](/docs/errors#INSUFFICIENT_SCOPE), and `error.details.required_scope` names the missing one. Keys issued before scopes existed have every read scope.

## Expiry and revocation

A key may carry an expiry time; after it, the key gets `401`. Revoking a key takes effect on the next request.

## Rotate without downtime

An organization can hold more than one live key, so rotation never needs a gap:

1. Ask for a new key. The old one keeps working.
2. Deploy the new key everywhere you call the API.
3. The old key gets an expiry a short time ahead, so anything you missed fails loudly before it is gone.
4. When the expiry passes, the old key stops working.

## Keep keys on the server

- Keep keys in a secrets manager or in environment variables your platform injects at run time.
- Never put a key in source control, a browser bundle or a mobile app.
- If a key leaks, ask for it to be revoked straight away.