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.

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`

curl JavaScript Python PHP Go

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

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

import os
import requests

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

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

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.

curl

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 for every code.