# Authentication

> Send your key in the X-API-Key header; what a key controls and how to keep it safe.

Source: https://api.tailend.dev/docs/authentication

Send your key in the `X-API-Key` header on every `/v1` request.

```bash
curl -H "X-API-Key: $TAILEND_API_KEY" https://api.tailend.dev/v1/metros
```

There's no query-string form — a key in a URL ends up in access logs, browser history, and `Referer` headers, so it isn't accepted there.

## Getting a key

Key issuance isn't self-service yet — ask us and we'll set one up for your account. The plaintext key is returned once — store it as a secret; we only keep a hash. Keys look like `tl_` + 8 hex + `_` + 48 hex; the `tl_` + 8 hex part is the key's display prefix, which is how it's identified in lists and usage, and is never enough to authenticate.

`X-API-Key` is the only credential `/v1` accepts.

## What a key controls

A key carries its own metro, resource-type, and add-on entitlements — access is evaluated per key, not just per account. A request outside a key's entitlement is refused; see [Errors](https://api.tailend.dev/docs/errors.md) for the exact codes.

## What to do

- Keep keys server-side: out of browser bundles, client code, and source control.
- Rotate a key rather than sharing one across environments — rotation leaves the old key working through a grace window, so nothing goes down mid-rollover.
- A missing, invalid, or revoked key returns `401`; a valid key outside its entitlement returns `403`. See [Errors](https://api.tailend.dev/docs/errors.md) for what each means and what to do next.