Spaces:
Sleeping
Sleeping
File size: 3,762 Bytes
8e8c6a4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | # 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
|