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

# 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:

{
  "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

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

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

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