Authentication and API keys

Every request for a dataset carries the key in the Authorization header, using the Bearer scheme. A key consists of the prefix qk_live_ and 40 further characters. The API only accepts it in the header, not as a parameter in the address. That way it never ends up in server logs or browser history.

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn" \
  -H "Authorization: Bearer $QK_KEY"

const res = await fetch("https://api.quellenkontor.dev/v1/hr/mindestlohn", {
  headers: { Authorization: `Bearer ${process.env.QK_KEY}` },
});

import os, requests

r = requests.get(
    "https://api.quellenkontor.dev/v1/hr/mindestlohn",
    headers={"Authorization": f"Bearer {os.environ['QK_KEY']}"},
    timeout=15,
)

The SDK and CLI set the header themselves. They read the key from QK_KEY if you do not pass one.

A few addresses are open so you can explore the API before you have an account. They do not count against any quota.

Every other request for a dataset needs a key, even on the Free plan. One exception is the sandbox: three datasets respond without an account too, tightly limited in return.

Sandbox: three datasets without an account

Minimum wage, Public holidays, Contribution ceilings answer a request without the Authorization header, limited to 50 requests a day per IP address (a rolling window, not a fixed calendar day). Useful for a first try in the console or a public widget without a backend of your own. As soon as you send an Authorization header, valid or not, the sandbox no longer applies, and the normal path with a key takes over.

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn?datum=2027-01-15"

The response is the same as with a key, plus a note in the field hinweise and the header X-Kostenloser-Schluessel. For every dataset and a monthly instead of a daily quota, a free key is worth it, see Quickstart.

• The key belongs on the server: in an environment variable, or a secret store such as Environment Variables on Vercel or Secrets in GitHub Actions.
• Never in frontend code, mobile apps or public repositories. Anything that runs in the browser can be read by any visitor.
• Files such as .env belong in .gitignore.
• We only store a hash of the key. That means we cannot show you a lost key again, only let you generate a new one.

Create a separate key for every environment and every application, for example "Production", "Staging" and "Development". Your account shows, for each key, when it was last used. The quota applies to the whole account, not per key.

When an employee leaves, or you rotate keys on a schedule, swap them in four steps without a single request failing:

1. Generate a new key in your account. The old one stays active.
2. Put the new key in your configuration and redeploy your application.
3. Check in your account that the old key is no longer used: the "Last used" column stops advancing.
4. Revoke the old key.

A revoked key stops working immediately: the next request made with it gets status 401 and the code schluessel_ungueltig. A revocation cannot be undone. Generate a new key afterward.

Responses with status 401 also carry the header WWW-Authenticate. The MCP server likewise responds with 401 when a key is missing, so clients can recognize that one is needed. All other codes are listed under Errors.

The account on the website does not use passwords. You sign in with a link sent by email that is valid for 20 minutes and works only once. After that you stay signed in for 30 days. "Sign out" ends the session on every device. Your API keys are unaffected by this: they remain valid until you revoke them.