Authenticate requests to the BugViper API

Pass a Firebase ID token as a Bearer token in the Authorization header on every BugViper API request. Tokens expire after one hour and must be refreshed.

BugViper uses Firebase Authentication to verify every API request. Every endpoint except the webhook receiver requires a Firebase ID token passed as a Bearer token in the Authorization header. Requests with a missing, malformed, or expired token receive a 401 Unauthorized response.

Required header

Include the following header on every API request:

Authorization: Bearer <FIREBASE_ID_TOKEN>

Replace <FIREBASE_ID_TOKEN> with a valid, unexpired ID token obtained from Firebase.

Obtaining a token

Firebase issues ID tokens through its client SDKs. The exact method depends on the platform you are building on:

• Web (JavaScript): Call user.getIdToken() on the User object returned by the Firebase Auth SDK.
• Mobile (Android / iOS): Call getIdToken() on the FirebaseUser object.
• Server / CI: Use the Firebase Auth REST API to exchange credentials for an ID token.

Token expiration and refresh

Firebase ID tokens expire one hour after they are issued. When a token expires, the server returns:

{
  "detail": "Token has expired. Please sign in again."
}

To keep your session alive without requiring the user to log in again, use the Firebase refresh token flow:

1. Store the refresh token returned alongside the ID token when the user first signs in.
2. Exchange the refresh token for a fresh ID token using the Firebase Auth REST endpoint POST https://securetoken.googleapis.com/v1/token.
3. Pass the new ID token in subsequent requests.

The Firebase client SDKs handle this automatically when you call user.getIdToken(/* forceRefresh */ true).

Example request

curl https://your-bugviper-instance/api/v1/repos/ \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

Error responses

Status	detail message	Cause
401	Missing or malformed Authorization header. Expected: Bearer <token>	No Authorization header, or header does not start with Bearer
401	Empty token in Authorization header	Bearer prefix present but token value is blank
401	Token has expired. Please sign in again.	ID token is older than one hour
401	Token has been revoked. Please sign in again.	Token was revoked in the Firebase console
401	Invalid token.	Token signature is invalid or issued for a different project

Webhook endpoints (POST /api/v1/webhook/onComment and POST /api/v1/webhook/marketplace) use HMAC-SHA256 signature verification via the X-Hub-Signature-256 header, not Firebase tokens. These endpoints are called by GitHub automatically and bypass Firebase authentication entirely.