Documentation

This is a basic overview on how BrownieGate works.

How it works — Quick explanation

BrownieGate acts as an authentication server and SSO provider. Typical flow:

1. The user clicks "Login with BrownieGate" in your app; the app opens the BrownieGate auth endpoint (usually in a new window/tab) and includes the project's UUID in the request headers (project-uuid).
2. The user authenticates on BrownieGate. On success BrownieGate creates a one-time code and a timestamp, stores them server-side, then redirects the browser back to your project's configured callback URL with an encrypted payload, e.g. {"code": "<one_time_code>", "timestamp": "ISO8601"} (encrypted with the project's encryption key provided at setup).
3. Your project's callback endpoint receives the redirect and encrypted payload. Your server decrypts the payload using the project's encryption key and extracts the code and timestamp.
4. Your server calls BrownieGate's verification endpoint (server-to-server), sending the code with the headers: project-uuid and authorization (your API key). BrownieGate checks the code exists and that the timestamp is fresh (not older than 1 minute); valid codes are single-use and removed after verification.
5. If verification succeeds, BrownieGate returns success and the associated user_id. Your server can then call /api/user/get_data or /api/user/get_pfp (with project-uuid, authorization and user_id) to retrieve the user fields (projects are only allowed to get user data that the user has consented to).
6. Your site establishes a session for the user (create a short-lived server session token or set a secure HttpOnly cookie, or use /api/cookie/generate), and continues with normal authenticated flows. Keep the API key and the project encryption key on the server only.

Files & repos to check

• BrownieGate Python package — helper client for server-side integration.
• Usage example repo — complete sample app using BrownieGate.
• Flask login example repo — Small login example using flask-login.