> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantcite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Session-based authentication for Unified Transaction APIs

## Authentication Flow

The Unified Transaction APIs use session-based authentication for enhanced security. Follow these steps to authenticate:

### Step 1: Authenticate

**POST** `/api/v1/authenticate`

Authenticate with your API key to receive a session token.

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://data.quantcite.com/api/v1/authenticate" \
       -H "Content-Type: application/json" \
       -d '{
         "api_key": "YOUR_API_KEY"
       }'
  ```

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

  response = requests.post(
      "https://data.quantcite.com/api/v1/authenticate",
      json={"api_key": "YOUR_API_KEY"}
  )

  data = response.json()
  session_token = data["session_token"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://data.quantcite.com/api/v1/authenticate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      api_key: 'YOUR_API_KEY'
    })
  });

  const data = await response.json();
  const sessionToken = data.session_token;
  ```
</CodeGroup>

#### Request Body

| Field     | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `api_key` | string | Yes      | Your API key |

#### Response

```json theme={null}
{
  "success": true,
  "message": "Authenticated successfully as premium user",
  "session_token": "12345678-1234-1234-1234-123456789abc",
  "user_id": "cb88461f-421a-4ac8-9722-afe248a40ae6",
  "user_tier": "premium",
  "expires_at": 1695134400000
}
```

#### Response Fields

| Field           | Type    | Description                                                 |
| --------------- | ------- | ----------------------------------------------------------- |
| `success`       | boolean | Whether authentication was successful                       |
| `message`       | string  | Human-readable success message                              |
| `session_token` | string  | Session token for subsequent requests                       |
| `user_id`       | string  | Unique user identifier                                      |
| `user_tier`     | string  | User's billing tier (basic, premium, developer, enterprise) |
| `expires_at`    | number  | Session expiration timestamp (Unix milliseconds)            |

### Step 2: Use Session Token

Include the session token in the `Authorization` header for all subsequent API requests:

```
Authorization: Bearer 12345678-1234-1234-1234-123456789abc
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://data.quantcite.com/api/v1/transactions" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer 12345678-1234-1234-1234-123456789abc" \
       -d '{
         "exchange": "bybit",
         "transaction_types": ["deposits", "withdrawals"]
       }'
  ```

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

  headers = {
      "Authorization": f"Bearer {session_token}",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://data.quantcite.com/api/v1/transactions",
      headers=headers,
      json={
          "exchange": "bybit",
          "transaction_types": ["deposits", "withdrawals"]
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://data.quantcite.com/api/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      exchange: 'bybit',
      transaction_types: ['deposits', 'withdrawals']
    })
  });
  ```
</CodeGroup>

## API Key Management

API keys are generated by administrators and provided to authorized users. Each key is associated with a specific billing tier and usage limits.

<Warning>
  API keys are provided by QuantCite administrators. Contact support to get your production API keys.
</Warning>

## Session Management

### Session Duration

* **Duration**: 24 hours from creation
* **Auto Expiry**: Sessions automatically expire
* **Renewal**: Authenticate again to get a new session token

### Check Session Status

**GET** `/api/v1/session-status`

Check the status of your current session.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://data.quantcite.com/api/v1/session-status" \
       -H "Authorization: Bearer your_session_token"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://data.quantcite.com/api/v1/session-status",
      headers={"Authorization": f"Bearer {session_token}"}
  )
  ```
</CodeGroup>

#### Success Response

```json theme={null}
{
  "authenticated": true,
  "user_id": "cb88461f-421a-4ac8-9722-afe248a40ae6",
  "user_tier": "premium",
  "expires_at": 1695134400000,
  "created_at": 1695048000000,
  "message": "Session is valid"
}
```

#### Invalid Session Response

```json theme={null}
{
  "authenticated": false,
  "message": "Invalid or expired session token"
}
```

## Error Handling

### Authentication Errors

| Status Code | Error                 | Description                      |
| ----------- | --------------------- | -------------------------------- |
| `400`       | `missing_api_key`     | API key not provided in request  |
| `401`       | `invalid_api_key`     | API key is invalid or not found  |
| `401`       | `api_key_disabled`    | API key has been disabled        |
| `429`       | `rate_limit_exceeded` | Too many authentication attempts |

### Session Errors

| Status Code | Error                   | Description                       |
| ----------- | ----------------------- | --------------------------------- |
| `401`       | `session_expired`       | Session token has expired         |
| `401`       | `invalid_session`       | Session token is invalid          |
| `401`       | `missing_authorization` | Authorization header not provided |

<Tip>
  Store session tokens securely and implement automatic renewal when sessions expire.
</Tip>