API_KEY_QUICK_START.md

# API Key Authentication - Quick Start Guide

## Summary

API key authentication has been successfully implemented for external applications. The `/api/extract` endpoint now supports both JWT Bearer tokens and API keys.

## Quick Steps to Use from External Applications

### 1. Get an API Key

**Option A: Via Web UI (if available)**
- Log in to your account
- Navigate to API Keys section
- Create a new API key
- Copy and store it securely

**Option B: Via API**

```bash
# Step 1: Authenticate and get JWT token
curl -X POST https://your-api-url/api/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{"email": "your-email@company.com"}'

# Step 2: Verify OTP
curl -X POST https://your-api-url/api/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "your-email@company.com", "otp": "123456"}'

# Step 3: Create API key (use token from step 2)
curl -X POST https://your-api-url/api/auth/api-key/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'
```

**Response:**
```json
{
  "success": true,
  "api_key": "sk_live_abc123...",  // ⚠️ SAVE THIS!
  "key_prefix": "sk_live_abc...",
  "message": "API key created successfully. Store this key securely - it will not be shown again!"
}
```

### 2. Use API Key to Extract Documents

```bash
curl -X POST https://your-api-url/api/extract \
  -H "X-API-Key: sk_live_abc123..." \
  -F "file=@document.pdf" \
  -F "key_fields=Invoice Number,Invoice Date,Total Amount"
```

## Authentication Methods

The `/api/extract` endpoint accepts **either**:

1. **API Key**: `X-API-Key: sk_live_...` header
2. **JWT Token**: `Authorization: Bearer <token>` header

## New Endpoints

- `POST /api/auth/api-key/create` - Create new API key (requires JWT)
- `GET /api/auth/api-keys` - List your API keys (requires JWT)
- `DELETE /api/auth/api-key/{key_id}` - Deactivate API key (requires JWT)

## Security Features

- ✅ API keys are hashed (SHA-256) before storage
- ✅ Only key prefix shown when listing keys
- ✅ Usage tracking (`last_used_at` timestamp)
- ✅ Soft delete (deactivation) support
- ✅ One key per user account

## Example Code

### Python
```python
import requests

API_KEY = "sk_live_abc123..."
url = "https://your-api-url/api/extract"

with open("document.pdf", "rb") as f:
    response = requests.post(
        url,
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"key_fields": "Invoice Number,Invoice Date"}
    )
    print(response.json())
```

### JavaScript
```javascript
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('document.pdf'));
form.append('key_fields', 'Invoice Number,Invoice Date');

axios.post('https://your-api-url/api/extract', form, {
  headers: {
    'X-API-Key': 'sk_live_abc123...',
    ...form.getHeaders()
  }
}).then(response => console.log(response.data));
```

## Full Documentation

See `EXTERNAL_API_DOCUMENTATION.md` for complete documentation with:
- Detailed API reference
- Error handling
- Response formats
- Multiple language examples (Python, JavaScript, PHP)
- Best practices

## Database Migration

The new `api_keys` table will be created automatically when you restart the application (SQLAlchemy's `create_all` handles this).

## Testing

1. Start your backend server
2. Create an API key using the steps above
3. Test the extraction endpoint with the API key
4. Verify the response contains extracted data

## Notes

- API keys are shown **only once** when created - store them securely!
- Business email required for account creation
- Max file size: 4 MB
- Supported formats: PDF, PNG, JPEG, TIFF