Authentication
How bots prove who they are, what a bot token can and cannot do, and how to keep it safe.
On this page
Bot tokens
A bot token looks like palloo_bot_ followed by 43 more characters (32 random bytes in base64url). Palloo shows it once, when the bot is created or its token is regenerated, and stores only a hash of it. Tokens do not expire.
Send it on every REST request in the Authorization header with the Bearer scheme:
GET /v1/users/@me HTTP/1.1
Host: api.palloo.app
Authorization: Bearer palloo_bot_...On the gateway the token goes in the identify frame instead: {"op": "identify", "d": {"token": "palloo_bot_..."}}.
Use
Bearer, notBot. Discord bots sendAuthorization: Bot <token>. Palloo accepts only theBearerscheme (in any letter case), for bots and people alike, and answers anything else with401 unauthenticated.
A missing, wrong or revoked token answers 401 with the code unauthenticated and a WWW-Authenticate: Bearer header.
What a bot can call
A bot calls the same API as the Palloo app, and the server checks its permissions exactly as it would for a person. A few things only make sense for a person, and a bot token gets 403 bots_not_allowed there: logging out, sessions, passwords and two-factor settings, friends and blocks, privacy and notification settings, push subscriptions, creating servers, accepting invites, creating or managing bots, adding bots to servers, using slash commands, and reporting.
The other way round, only bots can register slash commands and answer interactions. A person's token gets 403 bot_required there.
The API reference lists only the operations a bot (or a webhook or Log in with Palloo app) can call, and marks the ones that are for bots only.
Two account rules for people never apply to bots: bots never need to confirm a second factor, and they are not held back when the instance's terms of service change.
Other tokens
| Prefix | What it is | Where it goes |
|---|---|---|
palloo_bot_ |
A bot's token | Authorization: Bearer and gateway identify |
palloo_wh_ |
A webhook's token | In the webhook URL, or Authorization: Webhook <token> (Incoming webhooks) |
palloo_int_ |
One interaction's response token | In the interaction callback path, together with the bot token (Slash commands) |
palloo_oat_, palloo_ort_ |
Log in with Palloo access and refresh tokens | The userinfo and token endpoints only (Log in with Palloo) |
The prefixes let secret scanners recognize a leaked token.
Keeping the token safe
- Keep it out of your code and out of version control. Read it from an environment variable or your host's secret store.
- Never put it in a web page, a mobile app or anything else you hand to users. Anyone who has it controls the bot.
- Never put it in a URL. Proxies and logs keep URLs.
- Give the bot only the permissions it needs in each server. A leaked token can do whatever the bot's roles allow.
- Turn on two-factor authentication for your own account. Creating a bot and regenerating its token then need a fresh second factor.
Regenerating a token
If a token leaks, or you lose it, regenerate it: in Settings, Bots, select Regenerate token next to the bot. The new token is shown once.
The old token stops working at once. Every gateway connection that identified with it, on every server process, closes with code 4003, so your program has to be restarted with the new token. Deleting the bot does the same and also removes it from every server.
Only the bot's owner can regenerate its token, delete it or change its settings. Bots cannot manage bots.