# Authentication

How API keys work, the difference between read and read-write keys, and what happens when your plan changes.


The KleioBase API authenticates every request with an API key sent as `Authorization: Bearer kb_live_...`. Keys are created at [Settings > Developer](/settings/developer) and need a paid plan.

Every request carries your API key as a bearer token:

```bash
curl https://kleiobase.com/api/v1/workspaces \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

## Creating and revoking keys

Manage keys at [Settings > Developer](/settings/developer).

- Keys start with `kb_live_`.
- The full key is shown once, when you create it. KleioBase keeps only a hash, so a lost key cannot be recovered. Create a new one and revoke the old one.
- You can have up to 10 active keys at a time. Revoked keys do not count.
- Revoking a key stops it working immediately.
- Give each key a name that says where it is used, so you know which one to revoke if it leaks.

## Read and read-write keys

- A **read** key can only make `GET` requests. Anything else returns `403 forbidden`.
- A **read and write** key can also create, edit, merge and delete.

Use a read key wherever you only need to look at data.

## Which plans can use the API

API access needs a paid plan: Researcher, Archivist or Professional. An Explorer account gets `403 forbidden` on every request.

Your plan is checked on each request, so a downgrade takes effect on the very next call. Rate limits follow your plan too. See [Rate limits](/developers/docs/rate-limits).

## Keys are personal

A key acts as you, on your workspaces, and is meant for your own research: scripts, backups, your own tools. Do not share it or put it in code you publish. Building a product on KleioBase? [Contact us](/contact).

## Authentication errors

A missing, malformed, unknown or revoked key returns `401 unauthorized`. Repeated failed attempts from one IP address are limited per IP, so a script with a bad key should stop rather than retry in a loop. See [Errors](/developers/docs/errors).

Canonical: https://kleiobase.com/developers/docs/authentication