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

# Login

> Authenticate with email and password or an OAuth provider

## Email / Password Login

### Endpoint

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

### Request Body

<ParamField body="email" type="string" required>
  Registered email address
</ParamField>

<ParamField body="password" type="string" required>
  Account password
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.superbox.ai/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "SecurePass123!"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.superbox.ai/api/v1/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "SecurePass123!",
    }),
  });

  const data = await response.json();
  ```

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

  response = requests.post(
      "https://api.superbox.ai/api/v1/auth/login",
      json={
          "email": "user@example.com",
          "password": "SecurePass123!",
      },
  )

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

## Provider Login (Google / GitHub)

Exchange a Firebase-issued ID token or OAuth access 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 obtained from the provider. 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

```bash 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-google-id-token>"
  }'
```

## Response

Both endpoints return the same response shape.

<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. Use with `/auth/refresh` to get a new ID token.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Seconds until the ID token expires (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 - Invalid Credentials theme={null}
  {
    "status": "error",
    "detail": "Invalid email or password"
  }
  ```

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

## Token Refresh

Use the refresh token to obtain a new ID token before the current one expires.

### Endpoint

```
POST /api/v1/auth/refresh
```

### Request Body

<ParamField body="refresh_token" type="string" required>
  Refresh token from a previous login or register response
</ParamField>

### Example

```bash theme={null}
curl -X POST https://api.superbox.ai/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "AMf-vByW3..."}'
```

## Using the Token

Include the `id_token` in all authenticated API requests:

```bash theme={null}
curl https://api.superbox.ai/api/v1/servers \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6..."
```