# CORS Issues with File Uploads

When integrating Cloud Slicer's file upload functionality into a web application, you may encounter CORS (Cross-Origin Resource Sharing) errors when attempting to upload files directly from the browser. This guide explains why this happens and how to resolve it.

## Understanding the Problem

CORS errors occur when a web browser blocks requests from your application to the Cloud Slicer API due to security restrictions. Browsers enforce same-origin policies to prevent malicious scripts from making unauthorized requests to external APIs.

## File Upload Routes

Cloud Slicer provides two routes for uploading files, each designed for different use cases:

### Direct Upload (Server-Side Only)

```
POST /v1/file
```

- **Use case:** Server-to-server communication, CLI tools, testing
- **Authentication:** Requires API token in Authorization header
- **CORS:** Not browser-compatible (will cause CORS errors)
- **Best for:** Backend services, Swagger/API playground testing

### Public Upload (Browser-Compatible)

```
GET /v1/file/upload-id  (Step 1: Generate upload ID)
POST /v1/file/public/{upload-id}  (Step 2: Upload file)
```

- **Use case:** Browser-based web applications
- **Authentication:** Temporary upload ID (no API token in browser)
- **CORS:** Browser-compatible
- **Best for:** Frontend applications, client-side uploads

## Solution: Two-Step Upload Process

To prevent CORS errors in browser-based applications, use the two-step upload process:

### Step 1: Generate Upload ID

Request a temporary upload ID from your backend server:

```javascript
// Backend endpoint (your server)
const response = await fetch('https://api.cloudslicer3d.com/v1/file/upload-id', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${YOUR_API_TOKEN}`
  }
});

const { upload_id } = await response.json();
// Return upload_id to your frontend
```

**Key points:**
- This request must be made from your backend server (not the browser)
- Requires your Cloud Slicer API token
- Returns a temporary `upload_id` that expires in 1 hour
- The upload ID is invalidated after a successful upload or expiration

### Step 2: Upload File from Browser

Use the upload ID to upload the file directly from the browser:

```javascript
// Frontend (browser)
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch(`https://api.cloudslicer3d.com/v1/file/public/${upload_id}`, {
  method: 'POST',
  body: formData
  // No Authorization header needed
});

const result = await response.json();
console.log('Upload successful:', result);
```

**Key points:**
- This request is made from the browser
- No API token required (uses temporary upload ID instead)
- CORS-compatible endpoint
- Returns standard file upload response with `file_id`

## Security Considerations

- **Never expose your API token in frontend code** - Always generate upload IDs from your backend
- Upload IDs are single-use and expire after 1 hour
- Upload IDs are immediately invalidated after a successful upload
- Failed uploads do not consume the upload ID (can retry with same ID)

## When to Use Each Method

| Scenario | Recommended Route |
|----------|-------------------|
| Web application file upload | Public upload (2-step process) |
| Mobile app file upload | Public upload (2-step process) |
| Server-side automation | Direct upload (`POST /v1/file`) |
| CLI tools | Direct upload (`POST /v1/file`) |
| Testing in Swagger/API playground | Direct upload (`POST /v1/file`) |

## Troubleshooting

### Still Getting CORS Errors?

- Verify you're using the `/v1/file/public/{upload_id}` endpoint, not `/v1/file`
- Ensure the upload ID is generated from your backend (not in browser)
- Check that the upload ID hasn't expired (valid for 1 hour)
- Confirm the upload ID hasn't already been used

### Upload ID Not Working?

- Upload IDs expire after 1 hour
- Upload IDs are single-use (invalidated after successful upload)
- Verify your backend is successfully retrieving the upload ID

## Need Help?

If you're still experiencing issues with file uploads:

- Check the [API Reference](/api) for detailed endpoint documentation
- Visit our [GitHub Issues](https://github.com/Cloud-Slicer/cloud-slicer-docs/issues)
- Join our [Discord community](https://discord.gg/CVmtSMVmVs) for live support