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.

BurnGuard supports three authentication paths: OAuth via GitHub, OAuth via Google, and WebAuthn passkeys. The OAuth flows are browser-redirect flows — the dashboard navigates the user to the provider’s authorization page and the callback handler sets up a server-side session. Passkey flows use two-step begin/finish calls driven by the @simplewebauthn/browser library on the frontend. After any successful login the caller receives a session_id that must be passed as Authorization: Bearer session_<id> on all protected endpoints.

​
OAuth — GitHub

​
GET /v1/auth/github

Redirects the browser to GitHub’s OAuth authorization page. The server constructs the URL with client_id, scope=user:email, and prompt=consent then issues an HTTP 302 Found. Auth: Public — no session required. Request: No parameters or body. Response: 302 Found redirect to https://github.com/login/oauth/authorize. 
curl -i https://api.burnguard.run/v1/auth/github
# HTTP/1.1 302 Found
# Location: https://github.com/login/oauth/authorize?client_id=...

​
GET /v1/auth/github/callback

Handles the OAuth callback from GitHub. The handler exchanges the code query parameter for an access token, fetches the GitHub user profile (and primary verified email if not public), upserts the user record, creates a server-side session, then issues a 303 See Other redirect back to the frontend with session_id as a query parameter. Auth: Public — called by GitHub, not directly by users.
​
code
string
required
The authorization code returned by GitHub after the user grants access.
Response: 303 See Other redirect to {FRONTEND_URL}/auth/callback?session_id=<session_id>. 
# GitHub redirects the browser here automatically after authorization.
# Direct usage:
curl -i "https://api.burnguard.run/v1/auth/github/callback?code=abc123"
# HTTP/1.1 303 See Other
# Location: https://app.burnguard.run/auth/callback?session_id=session_...

​
OAuth — Google

​
GET /v1/auth/google

Redirects the browser to Google’s OAuth 2.0 authorization page. Requests email and profile scopes. Auth: Public — no session required. Request: No parameters or body. Response: 302 Found redirect to https://accounts.google.com/o/oauth2/v2/auth. 
curl -i https://api.burnguard.run/v1/auth/google
# HTTP/1.1 302 Found
# Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...

​
GET /v1/auth/google/callback

Handles the OAuth callback from Google. Exchanges the code for a Google access token, fetches the user’s profile from the Google userinfo endpoint, upserts the user record, creates a session, then redirects the browser back to the frontend. Auth: Public — called by Google’s OAuth service.
​
code
string
required
The authorization code returned by Google after the user grants access.
Response: 303 See Other redirect to {FRONTEND_URL}/auth/callback?session_id=<session_id>. 
curl -i "https://api.burnguard.run/v1/auth/google/callback?code=4/xyz"
# HTTP/1.1 303 See Other
# Location: https://app.burnguard.run/auth/callback?session_id=session_...

​
User Profile

​
GET /v1/auth/me

Returns the authenticated user’s profile along with a has_passkey flag indicating whether at least one WebAuthn credential is registered. Auth: Requires session — Authorization: Bearer session_<id>. Request: No parameters or body. Response:
​
id
number
Internal numeric user ID.
​
name
string
Display name sourced from the OAuth provider at sign-up.
​
email
string
Primary verified email address.
​
avatar_url
string
Profile picture URL from the OAuth provider.
​
github_id
number
GitHub numeric user ID. Present only when the account was created or linked via GitHub OAuth.
​
google_id
string
Google user ID string. Present only when the account was created or linked via Google OAuth.
​
has_passkey
boolean
true if the user has at least one registered WebAuthn passkey credential.
curl https://api.burnguard.run/v1/auth/me \
  -H "Authorization: Bearer session_abc123"

{
  "data": {
    "id": 42,
    "name": "Jane Dev",
    "email": "jane@example.com",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345",
    "github_id": 12345,
    "has_passkey": true
  }
}

​
Passkeys — Login

Passkey login uses a two-step WebAuthn discoverable-credential flow. The browser calls begin to retrieve a challenge, signs it with the device authenticator, then calls finish with the signed assertion. No session is required for either step.

​
POST /v1/auth/passkey/login/begin

Initiates a WebAuthn discoverable-credential login ceremony. The server calls BeginDiscoverableLogin, stores the challenge-keyed session temporarily, and returns PublicKeyCredentialRequestOptionsJSON to the caller. Auth: Public — no session required. Request: No body required. Response: PublicKeyCredentialRequestOptionsJSON — the WebAuthn options object to pass to navigator.credentials.get(). 
curl -X POST https://api.burnguard.run/v1/auth/passkey/login/begin \
  -H "Content-Type: application/json"

{
  "data": {
    "publicKey": {
      "challenge": "base64url-encoded-challenge",
      "timeout": 60000,
      "rpId": "burnguard.run",
      "userVerification": "preferred",
      "allowCredentials": []
    }
  }
}

​
POST /v1/auth/passkey/login/finish

Completes the WebAuthn login. The server validates the signed assertion against the stored challenge session, updates the credential sign count, creates a server session, and returns the session_id. Auth: Public — no session required. Request body: AuthenticationResponseJSON — the assertion produced by navigator.credentials.get(). Response:
​
session_id
string
The new session identifier. Store this and pass it as Authorization: Bearer session_<id> on all subsequent authenticated requests.
curl -X POST https://api.burnguard.run/v1/auth/passkey/login/finish \
  -H "Content-Type: application/json" \
  -d '{ "id": "credId", "rawId": "...", "response": { ... }, "type": "public-key" }'

{
  "data": {
    "session_id": "session_xxxxxxxxxxxxxxxx"
  }
}

​
Passkeys — Registration

Passkey registration requires an active session — users must be signed in via OAuth before they can add a passkey to their account.

​
POST /v1/auth/passkey/register/begin

Initiates the WebAuthn registration ceremony for the authenticated user. The server loads the user’s existing credentials (so they are excluded from being re-registered), calls BeginRegistration, stores the user-keyed session, and returns creation options. Auth: Requires session — Authorization: Bearer session_<id>. Request: No body required. Response: PublicKeyCredentialCreationOptionsJSON — the options object to pass to navigator.credentials.create(). 
curl -X POST https://api.burnguard.run/v1/auth/passkey/register/begin \
  -H "Authorization: Bearer session_abc123" \
  -H "Content-Type: application/json"

{
  "data": {
    "publicKey": {
      "rp": { "name": "BurnGuard", "id": "burnguard.run" },
      "user": { "id": "base64-user-id", "name": "jane@example.com", "displayName": "Jane Dev" },
      "challenge": "base64url-encoded-challenge",
      "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }],
      "timeout": 60000,
      "excludeCredentials": [],
      "authenticatorSelection": { "userVerification": "preferred" }
    }
  }
}

​
POST /v1/auth/passkey/register/finish

Completes the WebAuthn registration ceremony. The server validates the new credential against the stored session data, persists it, and returns 201 Created. Auth: Requires session — Authorization: Bearer session_<id>.
​
name
string
Optional human-readable label for this passkey (e.g. "MacBook Touch ID"). Defaults to "Passkey" if omitted.
Request body: RegistrationResponseJSON — the credential produced by navigator.credentials.create(). Response: 201 Created 
{
  "data": {
    "message": "Passkey registered successfully"
  }
}

curl -X POST "https://api.burnguard.run/v1/auth/passkey/register/finish?name=MacBook+Touch+ID" \
  -H "Authorization: Bearer session_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "id": "credId", "rawId": "...", "response": { ... }, "type": "public-key" }'
The passkeyRegisterFinish handler returns HTTP 201 Created (not 204). The response body contains a message field confirming successful registration.

Build docs developers (and LLMs) love

Get started for freeTalk to us