API keys

An API key lets a script, a dashboard or an AI assistant call Media as you, without your password and without your browser session. You can have several, name each one after what uses it, and revoke any of them at any time.

Creating a key

1. Open Settings and scroll to API keys.
2. Give the key a name you will recognise later, such as media mcp on my laptop or home dashboard.
3. Choose when it expires: 30 days, 90 days (the default), a year, or never.
4. Leave Allow writes unticked unless whatever uses the key needs to change things. See Read-only or read and write.
5. Select Create key.

The key appears once, in a yellow box, starting with media_pk_. Copy it now. Once you select I've saved it, Media cannot show it again; it keeps only a fingerprint of the key, not the key itself. If you lose a key, revoke it and create a new one.

Read-only or read and write

	read only	read and write
Browse the library, search, charts, activity, your own history	✓	✓
Change your wishlist, favourites, notes or collection		✓
Link or unlink a record's sources		✓
Administration actions, if you are an admin		✓
Create or revoke API keys
Change your password

A key without writes can only look. Anything that would change something is refused with a message saying the key is read-only. Choose this for anything that only needs to read, and for anything you are not sure about, such as an AI assistant exploring your library.

A key with writes can do almost anything you can do in the app, so treat it like your password.

No key can create or revoke API keys, or change your password, even one with writes. Those always need you, signed in. So a key that leaks cannot make itself a replacement before you revoke it, or lock you out of your account.

Using a key

Send it in the Authorization header:

curl https://api.media.binatang.nl/auth/me \
  -H "Authorization: Bearer media_pk_…"

x-api-key: media_pk_… works too, for tools that only let you set that header. The API reference lists what you can call; see Authentication for the details.

Seeing and revoking your keys

Settings → API keys lists your live keys with:

• their name;
• the first few characters of the key, so you can match it to where you used it;
• whether they can write;
• when they were last used;
• when they expire.

Revoke stops a key at once. Anything using it gets Not authenticated on its next request. Revoking cannot be undone, but creating a new key takes a moment.

Revoke a key as soon as you think it has leaked, for example if it was pasted into a chat or committed to a repository. Also revoke keys you no longer use.

If a key stops working

• You revoked it, or it expired. Create a new one.
• An administrator revoked it. They can do this for a key that has leaked; you are not notified. Create a new one, and ask them if you are unsure why.
• Your account was deleted. All of its keys are revoked with it.
• It is read-only and you tried to change something. The message says the key is read-only. Create a key with Allow writes if that is what you meant.