BugViper API Authentication — GitHub OAuth and Tokens

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

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.
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.
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.
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

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": "alice@example.com",
  "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.

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": "alice@example.com",
  "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.

Overview

Endpoints

BugViper API Authentication — GitHub OAuth and Tokens

How Authentication Works

Passing the Token

Token Expiry and Refresh

Auth Endpoint Reference

POST /api/v1/auth/ensure

GET /api/v1/auth/me

GET /api/v1/auth/github/repos

GET /api/v1/auth/installation

​How Authentication Works

​Passing the Token

​Token Expiry and Refresh

​Auth Endpoint Reference

​POST /api/v1/auth/login

​POST /api/v1/auth/ensure

​GET /api/v1/auth/me

​GET /api/v1/auth/github/repos

​GET /api/v1/auth/installation

How Authentication Works

Passing the Token

Token Expiry and Refresh

Auth Endpoint Reference

POST /api/v1/auth/login

POST /api/v1/auth/ensure

GET /api/v1/auth/me

GET /api/v1/auth/github/repos

GET /api/v1/auth/installation