Authentication

One token, one listing, and the reason a wrong bot id answers 404.

Every /api/v1 request carries the bot’s token in the Authorization header.

POST /api/v1/bots/1092194789458481202/stats HTTP/1.1
Host: discordbotlist.lol
Authorization: dbl_live_9f2c...
Content-Type: application/json

Bearer is optional:

Authorization: Bearer dbl_live_9f2c...

Both are accepted because the libraries that already post to several lists send both, and a developer adding this list should not have to find out which one we wanted.

The token identifies a bot, not a user

It is created by the owner for one listing and can only ever act on that listing. The id in the URL has to be the bot the token belongs to.

A mismatch answers 404, not 403. A 403 would confirm that the other bot exists to somebody holding an unrelated token, which is a lookup service we are not interested in running.

Situation	Status	Body
No Authorization header	401	Missing or malformed Authorization header.
Token we do not know	401	Invalid token.
Valid token, different bot in the URL	404	Bot not found.
Bot id that is not a Discord snowflake	404	Bot not found.

Rotating

Generate a new token on the bot’s edit page. The old one stops working the moment the new one is created — there is no grace period, so deploy the new value before you rotate if the bot is live.

We store only a hash of the token. That is the reason we cannot show it to you a second time, and the reason a database dump does not hand anybody a working credential.

Storing it

Treat it exactly like your Discord bot token: environment variable, not source control. Anyone holding it can post a server count and read your vote log — they cannot edit your listing, delete it, or touch your account.

What a token cannot do

• Read or write any other bot.
• Sign in, change the listing’s text, or reach the moderation panel.
• Retrieve a voter’s name, avatar or profile. The vote endpoints return ids and timestamps, and nothing else.