# Bigscreen Cloud API Overview

This document provides an overview of all API servers in the Bigscreen Cloud infrastructure.

## API Servers

The Bigscreen Cloud consists of three main API servers:

| API Server | Port | Purpose | Documentation |
|-----------|------|---------|---------------|
| **Auth API** | 3009 | Public authentication and media services | [AUTH_API.md](AUTH_API.md) |
| **Admin API** | 3999 | Private admin operations for factory, inventory, and moderation | [ADMIN_API.md](ADMIN_API.md) |
| **Cloud API** | 3002 | Multiplayer, rooms, social, and real-time features | [CLOUD_API.md](CLOUD_API.md) |

## Authentication

All API servers use a two-tier authentication system:

### 1. Application Key Authentication
- **Required for**: All API endpoints
- **Header**: `Authorization: <application-key>`
- **Purpose**: Identifies the application making the request

### 2. Access Token Authentication
- **Required for**: Most endpoints (exceptions noted in documentation)
- **Header**: `Authorization: Bearer <access-token>`
- **Purpose**: Identifies and authenticates the user
- **Obtained from**: Auth API login endpoints

### Special Authentication Types

- **Admin Access Token**: Required for Admin API endpoints, with specific access policies (Moderator, Fabricator, Inventory, etc.)
- **Refresh Tokens**: Used to renew access tokens without re-authentication
- **Single-Use Tokens**: Temporary tokens for specific operations

## Rate Limiting

Rate limiting is applied to:
- Auth endpoints (login, account creation)
- Pose API endpoints (scan downloads)
- Other sensitive endpoints as noted in documentation

## Response Format

All APIs follow REST conventions and return JSON responses with standard HTTP status codes:

- `200 OK` - Successful request
- `201 Created` - Resource created
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Missing or invalid authentication
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error

## Getting Started

### For VR App Developers
Start with the [Auth API](AUTH_API.md) for user authentication, then use the [Cloud API](CLOUD_API.md) for multiplayer features.

### For Admin/Factory Staff
Use the [Admin API](ADMIN_API.md) for factory operations, inventory management, and moderation tasks.

### For Website Developers
Use the [Auth API](AUTH_API.md) for user authentication and media services.

## Environment Setup

For local development setup instructions, see the main [README.md](../README.md).

## Testing

Integration tests for each API are located in the `tests/` folder. See [Running Tests](../README.md#running-tests) for more information.