Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Verifieddanny/BurnGuard/llms.txt

Use this file to discover all available pages before exploring further.

The BurnGuard dashboard at burnguard.run supports three ways to sign in: GitHub OAuth, Google OAuth, and WebAuthn passkeys. OAuth lets you reuse an existing identity you already trust. Passkeys are offered as a passwordless alternative — your biometric or hardware key stays on your device and is never transmitted, which means there is no password to phish or leak.

​
GitHub OAuth

Clicking Continue with GitHub on the login page navigates your browser to GET /v1/auth/github. The backend initiates the OAuth flow with GitHub, which redirects back to GET /v1/auth/github/callback after you authorise the app. On success the backend redirects your browser to the frontend callback URL with a session_id query parameter, which the frontend stores as a cookie and uses for subsequent API calls. No setup is required on your side beyond having a GitHub account.

​
Google OAuth

Clicking Continue with Google navigates to GET /v1/auth/google, which starts the OAuth flow with Google. After you approve access, Google redirects back to GET /v1/auth/google/callback, the backend creates or retrieves your account, and the frontend receives a session_id via the callback redirect. No setup is required on your side beyond having a Google account.

​
WebAuthn Passkeys

Passkeys use the WebAuthn standard and delegate authentication to a platform authenticator on your device — Touch ID on a Mac, Face ID on an iPhone, Windows Hello on a PC, or a hardware security key such as a YubiKey. Your biometric data never leaves your device.

​
Signing in with a passkey

1

Click 'Use a passkey'

On the login page, click the Use a passkey button. The frontend calls POST /v1/auth/passkey/login/begin, which returns a WebAuthn challenge.
2

Complete the biometric prompt

Your browser presents the platform authenticator (Touch ID, Face ID, Windows Hello, or security key). Confirm with your biometric or PIN.
3

Session created

The signed credential is posted to POST /v1/auth/passkey/login/finish. The backend verifies the assertion and returns { "session_id": "..." }. The frontend stores the value as a cookie and you land on the dashboard.

​
Registering a passkey

Passkey registration is available to users who are already signed in via GitHub or Google. You can add a passkey from the Settings → Authentication section.
1

Click 'Set up passkey'

In Settings, find the Authentication section and click Set up passkey. The frontend calls POST /v1/auth/passkey/register/begin — your active session Bearer token is sent automatically. Registration requires an authenticated session.
2

Complete the biometric prompt

Your browser asks you to register a new credential using Touch ID, Face ID, Windows Hello, or a hardware key. Approve the prompt.
3

Registration confirmed

The credential is posted to POST /v1/auth/passkey/register/finish. On success the Settings page shows Passkey — Registered and has_passkey on your profile becomes true.
Passkey registration requires an existing session — you must sign in with GitHub or Google at least once before you can enrol a passkey. After registration you can use the passkey as your sole sign-in method on any device that has the same platform authenticator synced (e.g. iCloud Keychain or Google Password Manager).

​
Session Management

After any successful sign-in the frontend stores a session_id value as a browser cookie. Every subsequent API call reads this cookie and attaches the value as a Bearer token in the Authorization header: 
Authorization: Bearer <session_id>
To retrieve the currently authenticated user’s profile, the frontend calls: 
GET /v1/auth/me
This endpoint requires a valid session and returns the User object: 
{
  "data": {
    "id": 42,
    "github_id": 1234567,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
    "has_passkey": true
  }
}
The User TypeScript type has these fields. Note that created_at and updated_at exist on the type definition and the database model but are not currently included in the GET /v1/auth/me response body — the handler returns only the fields listed with ✓ below:
FieldTypeIn /v1/auth/me responseDescription
idnumber✓Internal numeric user ID
github_idnumber (optional)✓GitHub account ID — present only if GitHub is linked
google_idstring (optional)✓Google account ID — present only if Google is linked
namestring✓Display name from the OAuth provider
emailstring✓Primary email address
avatar_urlstring✓Profile picture URL
has_passkeyboolean (optional)✓Whether a passkey credential is registered
created_atstring—Account creation timestamp (type only)
updated_atstring—Last profile update timestamp (type only)
A 401 response from /v1/auth/me means the session has expired or the cookie is missing — the frontend will redirect you back to /login.
The backend does not currently expose a logout endpoint. Signing out clears the client-side query cache and redirects to /login, but the underlying session_id cookie persists until it expires naturally. To fully invalidate the session server-side, a POST /v1/auth/logout endpoint would need to be added.

​
Self-Hosting Note

If you are running your own instance of the BurnGuard backend, set the WEBAUTHN_RP_ID environment variable to your own domain before starting the server: 
WEBAUTHN_RP_ID=yourdomain.example.com
The Relying Party ID must match the domain from which the browser initiates the WebAuthn ceremony. Using localhost is valid for local development. Mismatched RP IDs will cause passkey registration and login to fail with a browser-level error.

Build docs developers (and LLMs) love

Get started for freeTalk to us