# Authentication

> Every amodb request carries one key: 32 lowercase hex characters. Send it as api_key in the query or as an Authorization: Bearer header for TMDB style calls, and as apikey for OMDb style calls. Images need no key. A wrong key returns 401 with status_code 7, a suspended key 401 with status_code 10.

## Key format

A key is 32 lowercase hex characters, for example `0123456789abcdef0123456789abcdef`. It has the same shape as a TMDB v3 key, so fields and validators built for TMDB keys accept it.

amodb stores only a SHA-256 hash of each key. The full key is shown once, when you create it. If you lose it, delete it and create a new one.

## TMDB style calls

Send the key in one of two ways. Both work on every endpoint under `https://api.amodb.dev/3`.

| Method          | Example                          |
| --------------- | -------------------------------- |
| Query parameter | `?api_key=YOUR_KEY`              |
| Header          | `Authorization: Bearer YOUR_KEY` |

```bash
curl "https://api.amodb.dev/3/configuration" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const res = await fetch("https://api.amodb.dev/3/configuration", {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
```

```python
import os
import requests

res = requests.get(
    "https://api.amodb.dev/3/configuration",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
```

```php
<?php
$url = "https://api.amodb.dev/3/configuration?api_key=" . urlencode(getenv("AMODB_KEY"));
$config = json_decode(file_get_contents($url), true);
```

```go
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/configuration", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
res, err := http.DefaultClient.Do(req)
```

## OMDb style calls

The OMDb compatible endpoint takes the key as `apikey`, as OMDb does. It is the same key you use for TMDB style calls.

```bash
curl "https://api.amodb.dev/omdb/?t=Inception&y=2010&apikey=$AMODB_KEY"
```

## Images need no key

Image URLs on `img.amodb.dev` are public. Do not add your key to them: an `<img>` tag would expose it to every visitor.

## Keep keys on the server

A key in a browser bundle, a mobile app or a public repository is public. Anyone who copies it spends your request rate. Call amodb from your server, a serverless function or a build step, and pass only the data to clients.

- Store the key in an environment variable or a secret manager.
- Use one key per app or environment, with a label such as `production` or `staging`.
- Delete a key the moment it leaks. Calls with it fail at once.

## Errors

| HTTP | status_code | Meaning                                                          |
| ---- | ----------- | ---------------------------------------------------------------- |
| 401  | 7           | The key is missing, malformed or unknown.                        |
| 401  | 10          | The key is suspended. Write to <support@amodb.dev>.              |
| 402  | 36          | Your plan has expired. Pay for a new period on the pricing page. |

See [errors](https://amodb.dev/errors/) for every code.

## Questions and answers

### Is a Bearer header safer than api_key in the query?

Yes, a little. Query strings end up in server logs and browser history more often than headers. Both reach the same check, so use the header where your client allows it.

### How many keys can I create?

Up to 10 active keys per account. All of them share the request rate of your plan, so a second key does not add capacity.

### What happens to my keys when I change plans?

Nothing you need to do. Every active key picks up the new rate within a minute of the payment.

## Related pages

- [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes.
- [Rate limits](https://amodb.dev/rate-limits/): amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After.
- [Errors](https://amodb.dev/errors/): Every amodb error with its HTTP status, TMDB status_code and message, plus the OMDb error shape. What each one means and what your client should do next.
- [Acceptable use policy](https://amodb.dev/acceptable-use/): What you may and may not do with amodb: build apps, sites, bots and research on the data, but never share keys, resell raw access, dodge limits or attack it.

Updated: 2026-10-18. Source: https://amodb.dev/authentication/