falafy
EN
Download free

Public API v1 · @falafy/bot

OAuth2 and “sign in with Falafy”

Standard authorization code flow (RFC 6749) with PKCE S256, required for apps without a secret.

Scopes

  • identify: name, username and avatar (GET /api/v1/users/@me).
  • email: adds the email to /users/@me.
  • servers: the person’s servers (GET /api/v1/users/@me/servers).
  • bot: adds the bot to a server chosen on the consent screen.
  • applications.commands: with bot, installs the commands in the server; without bot, it is a user install (the bot may DM whoever authorized it).

Flow

// 1) mande a pessoa para:
https://falafy.com.br/app/oauth2/authorize?client_id=APP_ID&scope=identify%20email
  &redirect_uri=https%3A%2F%2Fseu.site%2Fcallback&response_type=code&state=XYZ
  &code_challenge=BASE64URL(SHA256(verifier))&code_challenge_method=S256

// 2) no callback, troque o code (form-urlencoded):
POST https://falafy.com.br/api/oauth2/token
grant_type=authorization_code&code=CODE&redirect_uri=https%3A%2F%2Fseu.site%2Fcallback
&client_id=APP_ID&code_verifier=VERIFIER        (ou client_secret=... em servidores)

// 3) use o token:
GET https://falafy.com.br/api/v1/users/@me
Authorization: Bearer fo_at_...

Register the exact redirect URIs in the portal. state comes back unchanged on the redirect: check it to prevent CSRF. Codes last 10 minutes and work once.

Tokens

The response is standard: access_token (1 hour), refresh_token (30 days), token_type: "Bearer", expires_in and scope. Refresh with grant_type=refresh_token: the old refresh token stops working (rotation). Revoke with POST /api/oauth2/token/revoke (token, client_id); that ends the whole authorization. GET /api/v1/oauth2/@me shows the app, scopes and expiry.

Installing bots

The portal link (/app/oauth2/authorize?client_id=...&scope=bot%20applications.commands&permissions=...) shows the consent screen with the server and permission choice. Only permissions the installer also has are granted, and Administrator never is. Private bots can only be installed by their owner. With “Require full OAuth2 authorization”, also pass redirect_uri and response_type=code.