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

# API keys and usage

> Reading needs no key. A key raises your limit and shows you your usage.

Every public endpoint works without a key, at **120 requests per minute per
address** ([limits](https://docs.tariffs.nlead.ch/limits.md)). A key is for integrations that need more, or
that want to subscribe to [tariff changes](https://docs.tariffs.nlead.ch/webhooks.md).

## Tiers

| Tier | Requests per minute |
| - | - |
| No key | 120, per address |
| `free` | 300 |
| `pro` | 1'200 |
| `enterprise` | 6'000 |

The limit is per key, wherever the requests come from.

## Getting a key

A `free` key is yours in a minute, without waiting for anyone:

```bash theme={null}
curl -X POST "$TARIFF_API/api/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example AG", "email": "dev@example.ch", "accept_terms": true}'
```

A link arrives at that address, good for 24 hours. Opening it shows your key,
once. Asking again for the same address replaces your free key, which is how a
lost key is replaced: only its hash is stored, so it cannot be shown again.

`pro` and `enterprise` keys are issued by the team that runs this service; ask
through [n:lead](https://nlead.ch/#contact).

> [!NOTE]
>
> Self-service sign-up opens with the terms of use. Until then the endpoint
> answers `404`, and keys are issued by hand.

## Sending your key

Either header works:

```bash theme={null}
curl -H "X-API-Key: $KEY" \
  "$TARIFF_API/api/v1/periods"

curl -H "Authorization: Bearer $KEY" \
  "$TARIFF_API/api/v1/periods"
```

Every response says which tier served it, in `X-API-Tier`, beside the usual
`X-RateLimit-*` headers.

> [!WARNING]
>
> A key that is unknown or revoked gets a `401`, not anonymous access. A typo in
> your configuration shows up at once instead of as a silently lower limit.

The key is shown once, when it is created. Only its hash is stored, so a lost
key cannot be recovered, only replaced.

## Your usage

```bash theme={null}
curl -H "X-API-Key: $KEY" \
  "$TARIFF_API/api/v1/usage?days=30"
```

```json theme={null}
{
  "name": "Example AG",
  "tier": "pro",
  "limit_per_minute": 1200,
  "usage": [
    {"day": "2026-11-01", "endpoint": "/api/v1/dsos/{id}/tariffs", "n": 5210},
    {"day": "2026-11-01", "endpoint": "/api/v1/tariffs/export", "n": 3}
  ]
}
```

Usage is counted per day and endpoint, with identifiers taken out of the path,
so five hundred operators read one by one count as one endpoint. Counts are
written about once a minute; the last minute may not show yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.