Authentication

Every request your bot makes carries its token in the Authorization header, with the word Bot in front:

GET /api/auth/me HTTP/1.1
Host: baff.gg
Authorization: Bot bfx_4f1c...

The gateway WebSocket uses the same header. That's the only way to log in as a bot: tokens aren't accepted in cookies or URLs.

#Check the token works

curl https://baff.gg/api/auth/me -H "Authorization: Bot $BOT_TOKEN"

You get the bot's account back:

{
	"id": "103712345678901248",
	"email": "bot-103712345678901248@bafflux.invalid",
	"username": "music_helper",
	"displayName": "Music Helper",
	"emailVerified": true,
	"status": "online",
	"customStatus": null,
	"avatarUrl": null,
	"bannerUrl": null
}

Bot accounts have a placeholder email that can't receive mail, and can't log in with a password.

A missing or wrong token gets 401 with {"error": {"code": "unauthorized", ...}}.

#Bot tokens and OAuth2 tokens

Authorization: Bot <token> is your bot acting as itself. Authorization: Bearer <token> is an OAuth2 access token: your app acting for a person who signed in with baff.gg, only within the scopes they allowed. Bearer tokens work on a handful of read-only routes (/api/users/@me, /api/users/@me/guilds, /api/users/@me/guilds/{serverId}/member, /api/oauth2/@me) and nowhere else. See OAuth2 and Login with baff.gg.

#Keeping the token safe

• Keep it in an environment variable or your host's secret store, never in code you share.
• baff.gg stores only a fingerprint of it, so nobody (us included) can show it to you again.
• If it leaks, Reset Token on the portal's Bot page. The old token stops working at once and the bot is disconnected; start it again with the new one.

#What bots can't do

Bots use the same API as the app, minus anything that only makes sense for a person. These answer 403 with code bots_not_allowed:

• Logging in, signing up, changing a password or username (/api/auth/* except GET /api/auth/me, /api/users/@me/password, /api/users/@me/username).

• Friends: anything under /api/users/@me/relationships.

• Making servers, joining with invite links, or joining servers from Discovery. Bots join servers only when someone adds them with the install link.

• Reporting messages, people or servers to baff.gg (POST /api/channels/{channelId}/messages/{messageId}/report, POST /api/users/{userId}/report, POST /api/servers/{serverId}/report).

• The Developer Portal, except registering their own commands.

• Authorizing other apps with OAuth2 (/oauth2/authorize), or using Authorized Apps.

Bots also only see what their permissions allow, exactly like people: channels hidden from their role don't exist as far as the API is concerned.