Home

TSun FF JWT API — Wiki

A lightweight, asynchronous Flask API that emulates the Free Fire / Garena guest‑login handshake to return a valid account JWT token in real time.

It is built around Protobuf message encoding, AES‑CBC request encryption, and async HTTPX for fast, accurate token generation. Access is gated by an API‑key layer backed by a Neon PostgreSQL database, and a small admin API lets you mint, list and revoke time‑limited keys.

---

⚡ At a glance

Language	Python 3.10+ (tested on 3.11)
Framework	Flask + Gunicorn (gevent workers)
Transport	async HTTPX
Encoding	Protocol Buffers (LoginReq / LoginRes)
Crypto	AES‑128‑CBC (PyCryptodome)
Database	Neon PostgreSQL (psycopg2)
Frontend	Static dashboard (/) — "TSun Jwt Maker"
License	MIT

---

🧭 Documentation

Page	What's inside
Getting Started	Clone, install dependencies, run locally
Configuration	Environment variables & remote config.json
API Reference	The /v1/auth token endpoint
Admin API & Key Management	Create / list / revoke API keys
How It Works	The full login handshake, step by step
Deployment	Docker, Docker Compose, VPS + Nginx, Vercel
Troubleshooting & FAQ	Common errors and fixes

---

🚀 What it does

Client ──GET /v1/auth/{apikey}?uid=&password=──►  TSun FF JWT API
                                                       │
                                 1. Garena OAuth guest token grant
                                 2. Build + AES‑encrypt Protobuf LoginReq
                                 3. POST to Free Fire MajorLogin
                                 4. Parse Protobuf LoginRes
                                                       │
Client ◄──────────  JSON { accountId, token, ... } ◄──┘

A successful response looks like:

{
  "accountId": "1234567897",
  "agoraEnvironment": "live",
  "ipRegion": "PK",
  "lockRegion": "PK",
  "notiRegion": "SG",
  "serverUrl": "https://clientbp.ggpolarbear.com",
  "accessToken": "f9596a1377d3daf61a",
  "token": "eyJhbGciOiJIUzI1NiIsInN2ciI6IjEiLCJ0eXAiOiJ..."
}

---

🔒 Important notes

• This project is intended for authorized, educational and research use against accounts you own or are permitted to test.
• It relies on guest UID + password credentials and never stores them — credentials are used only for the live handshake.
• Treat your VALID_API_KEY, ADMIN_KEY and DATABASE_URL as secrets. Never commit a real .env file. See Configuration.

---

👥 Credits

Developed by 𝙎ค૯𝙀𝘿✘🫀 · Team TSun FreeFire × Script Kittens.

Released under the MIT License.