BugViper API Authentication — GitHub OAuth and Tokens

Learn how to obtain a Firebase ID Token via GitHub OAuth and include it as a Bearer token on every protected BugViper API request.

BugViper uses Firebase Authentication backed by GitHub OAuth. Every protected API request must include a valid Firebase ID Token in the Authorization header. This page explains how the auth flow works, how to obtain a token, and documents every endpoint in the /api/v1/auth/ group.

How Authentication Works

1. Sign in with GitHub — The user visits the BugViper /login page (or a GitHub OAuth popup in the dashboard). They authorize the BugViper OAuth app, and GitHub returns a short-lived access token.
2. Call /api/v1/auth/login — BugViper’s frontend sends that GitHub access token to POST /api/v1/auth/login. The API fetches the user’s GitHub profile and creates or updates their BugViper user record.
3. Firebase issues an ID Token — Firebase generates a signed JWT (the ID Token) tied to the authenticated user. This token is valid for 1 hour and can be silently refreshed by the Firebase SDK.
4. Pass the token on every request — Include the token as a Bearer credential in the Authorization header for every protected endpoint.

Authorization: Bearer <Firebase ID Token>

Passing the Token

Here is an example using curl:

curl -X GET https://your-domain.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

You can copy a live token from the browser’s developer console while signed in to the BugViper dashboard: call await firebase.auth().currentUser.getIdToken() in the console to print the current JWT.

Token Expiry and Refresh

Firebase ID Tokens expire after 1 hour. The BugViper frontend refreshes them automatically using the Firebase SDK’s token refresh mechanism. For server-side or scripted integrations, call getIdToken(/* forceRefresh= */ true) on the Firebase user object before each batch of requests to ensure the token is still valid.

Passing an expired token returns HTTP 401 Unauthorized. Always refresh the token before it expires in long-running scripts or background jobs.

---

Auth Endpoint Reference

POST /api/v1/auth/login

Register a new user or sign in an existing one. Pass the GitHub OAuth access token obtained from GitHub’s OAuth flow. The API fetches the user’s GitHub profile and creates or updates the corresponding BugViper user record. Returns the full user profile.

curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"github_access_token": "gho_xxxxxxxxxxxx"}'

Request body

github_access_token · string · required

The GitHub OAuth access token obtained after the user completes the GitHub OAuth flow. Starts with gho_ for classic tokens.

Example request body

{
  "github_access_token": "gho_xxxxxxxxxxxx"
}

Example response

{
  "uid": "firebase-uid-abc123",
  "email": "[e-mail]",
  "displayName": "Alice Smith",
  "githubUsername": "alicesmith",
  "photoURL": "https://avatars.githubusercontent.com/u/12345678",
  "createdAt": "2024-09-01T10:00:00Z",
  "githubInstallationId": 987654,
  "accountType": "User",
  "repositorySelection": "selected"
}

---

POST /api/v1/auth/ensure

Ensures the authenticated user’s record exists. Call this on returning sessions when you already hold a valid Firebase ID Token but do not have a fresh GitHub access token — for example, when the page reloads and Firebase silently re-authenticates.

No request body is required. The API identifies the user from the Authorization header alone.

curl -X POST https://your-domain.com/api/v1/auth/ensure \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

Response: user profile object (same shape as /auth/login).

Use /api/v1/auth/ensure instead of /api/v1/auth/login for session restores. It is faster because it only verifies the existing user record without making an additional GitHub API call.

---

GET /api/v1/auth/me

Returns the authenticated user’s profile. Use this to verify the current token is valid and to retrieve profile data without going through the login flow again.

curl -X GET https://your-domain.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

Response fields

uid · string

Firebase user ID. Uniquely identifies the user across all BugViper services.

email · string

The user’s email address as provided by GitHub.

displayName · string

The user’s display name from their GitHub profile.

githubUsername · string

The user’s GitHub username (e.g., alicesmith).

photoURL · string

URL to the user’s GitHub avatar image.

createdAt · string

ISO 8601 timestamp of when the user account was first created in BugViper.

githubInstallationId · number | null

The GitHub App installation ID linked to this user’s account. null if the GitHub App has not been installed yet.

accountType · string

GitHub account type — "User" or "Organization".

repositorySelection · string

The repository selection scope chosen when installing the GitHub App — "all" or "selected".

Example response

{
  "uid": "firebase-uid-abc123",
  "email": "[e-mail]",
  "displayName": "Alice Smith",
  "githubUsername": "alicesmith",
  "photoURL": "https://avatars.githubusercontent.com/u/12345678",
  "createdAt": "2024-09-01T10:00:00Z",
  "githubInstallationId": 987654,
  "accountType": "User",
  "repositorySelection": "selected"
}

---

GET /api/v1/auth/github/repos

Returns the list of GitHub repositories accessible to the authenticated user. This is the same repository list you see when connecting repos in the BugViper dashboard.

curl -X GET https://your-domain.com/api/v1/auth/github/repos \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

This endpoint returns HTTP 400 if no GitHub access token is stored for the user. Make sure you have called POST /api/v1/auth/login at least once with a valid GitHub token before calling this endpoint.

Response: array of repository objects.

name · string

Short repository name (e.g., my-project).

full_name · string

Full repository name including the owner (e.g., alicesmith/my-project).

description · string | null

Repository description as set on GitHub.

language · string | null

Primary programming language detected by GitHub.

stargazers_count · number

Number of GitHub stars.

private · boolean

Whether the repository is private.

default_branch · string

Name of the repository’s default branch (e.g., main or master).

html_url · string

URL to the repository’s GitHub page.

Example response

[
  {
    "name": "my-project",
    "full_name": "alicesmith/my-project",
    "description": "A sample project",
    "language": "TypeScript",
    "stargazers_count": 42,
    "private": false,
    "default_branch": "main",
    "html_url": "https://github.com/alicesmith/my-project"
  }
]

---

GET /api/v1/auth/installation

Returns the GitHub App installation status for the currently authenticated user. Use this to determine whether the user has installed the BugViper GitHub App and linked it to their account — a prerequisite for receiving PR review webhooks.

curl -X GET https://your-domain.com/api/v1/auth/installation \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

Response fields

linked · boolean

true if the BugViper GitHub App is installed and successfully linked to this user’s account. false if the app has not been installed or the installation could not be resolved.

installationId · number | null

The GitHub App installation ID. Present when linked is true; null otherwise.

githubUsername · string | null

The GitHub username associated with this account.

settingsUrl · string | null

A direct link to the GitHub App installation settings page (https://github.com/settings/installations/{installationId}). Present when linked is true; null otherwise.

Example response — linked

{
  "linked": true,
  "installationId": 987654,
  "githubUsername": "alicesmith",
  "settingsUrl": "https://github.com/settings/installations/987654"
}

Example response — not linked

{
  "linked": false,
  "installationId": null,
  "githubUsername": "alicesmith",
  "settingsUrl": null
}

If linked is false, direct the user to install the BugViper GitHub App from the dashboard’s Settings page. Once installed, the next call to /api/v1/auth/installation will automatically attempt to link the pending installation to the user’s account.