> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Authenticate with Google or GitHub using OAuth

## 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](/api/auth/device-flow).

## Provider Login

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

### Endpoint

```
POST /api/v1/auth/login/provider
```

### Request Body

<ParamField body="provider" type="string" required>
  OAuth provider: `google` or `github`
</ParamField>

<ParamField body="id_token" type="string">
  Firebase ID token from `signInWithPopup` or `signInWithRedirect`. Use this **or** `access_token`.
</ParamField>

<ParamField body="access_token" type="string">
  OAuth access token from the provider. Use this **or** `id_token`.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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>"
    }'
  ```

  ```javascript JavaScript (Firebase SDK) theme={null}
  import { getAuth, signInWithPopup, GoogleAuthProvider } from "firebase/auth";

  const auth = getAuth();
  const provider = new GoogleAuthProvider();

  const result = await signInWithPopup(auth, provider);
  const idToken = await result.user.getIdToken();

  // Exchange with SuperBox API
  const response = await fetch("https://api.superbox.ai/api/v1/auth/login/provider", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ provider: "google", id_token: idToken }),
  });

  const { id_token, refresh_token } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.superbox.ai/api/v1/auth/login/provider",
      json={
          "provider": "google",
          "id_token": "<firebase-id-token>",
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response

<ResponseField name="id_token" type="string">
  Firebase ID token (JWT). Use as `Authorization: Bearer <id_token>`.
</ResponseField>

<ResponseField name="refresh_token" type="string">
  Refresh token for renewing the session.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Seconds until expiry (3600 = 1 hour).
</ResponseField>

<ResponseField name="email" type="string">
  Authenticated email address.
</ResponseField>

<ResponseField name="local_id" type="string">
  Firebase user ID.
</ResponseField>

### Success Response (200)

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

### Error Responses

<CodeGroup>
  ```json 401 - Token Invalid theme={null}
  {
    "status": "error",
    "detail": "OAuth authentication failed"
  }
  ```

  ```json 400 - Missing Provider theme={null}
  {
    "status": "error",
    "detail": "Invalid request: provider is required"
  }
  ```
</CodeGroup>

## CLI / Device Flow

For headless environments like the CLI, use the device authorization flow instead. See [Device Flow](/api/auth/device-flow) for details.