Skip to main content

​
Overview

SuperBox supports OAuth authentication via Google and GitHub. The flow depends on the client:
  • Web / Mobile: Use the Firebase SDK to obtain an ID token, then exchange it via POST /auth/login/provider.
  • CLI: Use the device authorization flow documented in Device Flow.

​
Provider Login

Exchange a provider-issued token for a SuperBox session token.

​
Endpoint

POST /api/v1/auth/login/provider

​
Request Body

​
provider
string
required
OAuth provider: google or github
​
id_token
string
Firebase ID token from signInWithPopup or signInWithRedirect. Use this or access_token.
​
access_token
string
OAuth access token from the provider. Use this or id_token.

​
Example Request

curl -X POST https://api.superbox.ai/api/v1/auth/login/provider \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "id_token": "<firebase-id-token>"
  }'

​
Response

​
id_token
string
Firebase ID token (JWT). Use as Authorization: Bearer <id_token>.
​
refresh_token
string
Refresh token for renewing the session.
​
expires_in
number
Seconds until expiry (3600 = 1 hour).
​
email
string
Authenticated email address.
​
local_id
string
Firebase user ID.

​
Success Response (200)

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "AMf-vByW3...",
  "expires_in": 3600,
  "email": "user@example.com",
  "local_id": "abc123def456"
}

​
Error Responses

{
  "status": "error",
  "detail": "OAuth authentication failed"
}

​
CLI / Device Flow

For headless environments like the CLI, use the device authorization flow instead. See Device Flow for details.