Authentication

The DocExtract API uses API keys to authenticate requests. All API requests must include your API key in the Authorization header.

API Keys

API keys are secret tokens that identify your application and grant access to the API. They come in two types:

Test Keys (sk_test_...)

• Use for development and testing
• Don't charge real credits
• Process documents with simulated AI
• Safe to use with sample data

Live Keys (sk_live_...)

• Use for production
• Charge real credits
• Process documents with production AI
• Keep strictly confidential

Getting Your API Key

1. Log in to your Adteco account
2. Navigate to DocExtract → Settings → API Keys
3. Click New Key
4. Enter a name and description
5. Select environment (Test or Live)
6. Choose permissions (scopes)
7. Copy your key immediately - you won't see it again!

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk_live_your_api_key_here

Example Requests

curl https://api.adteco.com/v1/extractors \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.adteco.com/v1/extractors', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
  },
});

const data = await response.json();

import requests

response = requests.get(
    'https://api.adteco.com/v1/extractors',
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)

data = response.json()

package main

import (
    "net/http"
    "io"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.adteco.com/v1/extractors", nil)
    req.Header.Set("Authorization", "Bearer sk_live_your_api_key")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
}

API Key Permissions (Scopes)

Control what each API key can access using scopes:

Scope Best Practices

• Principle of Least Privilege: Only grant necessary permissions
• Separate Keys: Use different keys for different applications
• Read-Only Keys: Use for monitoring and reporting
• Write Keys: Limit to trusted services only

Example: Creating a read-only monitoring key:

{
  "name": "Monitoring Dashboard",
  "scopes": [
    "documents:read",
    "extractors:read",
    "credits:read"
  ]
}

Security Best Practices

✅ Do This

• Store securely: Use environment variables or secret management systems
• Rotate regularly: Change keys every 90 days
• Monitor usage: Check for unexpected API calls
• Use HTTPS: Always use encrypted connections
• Revoke compromised keys: Immediately revoke if exposed

❌ Don't Do This

• Commit to Git: Never push keys to version control
• Hardcode in apps: Don't embed in source code
• Share keys: Each service should have its own key
• Use in browsers: Never expose keys in client-side code
• Reuse keys: Don't use the same key across environments

Environment Variables

Store your API key in environment variables:

# .env file
DOCEXTRACT_API_KEY=sk_live_your_api_key

# Load in your shell
export DOCEXTRACT_API_KEY=sk_live_your_api_key

// .env file
DOCEXTRACT_API_KEY=sk_live_your_api_key

// Load with dotenv
import dotenv from 'dotenv';
dotenv.config();

const apiKey = process.env.DOCEXTRACT_API_KEY;

# .env file
DOCEXTRACT_API_KEY=sk_live_your_api_key

# Load with python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('DOCEXTRACT_API_KEY')

# docker-compose.yml
services:
  app:
    image: myapp
    environment:
      - DOCEXTRACT_API_KEY=sk_live_your_api_key

Key Management

Creating Keys

curl -X POST https://api.adteco.com/v1/api-keys \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "description": "Key for production document processing",
    "environment": "live",
    "scopes": ["documents:read", "documents:write"],
    "expires_in_days": 90
  }'

Listing Keys

curl https://api.adteco.com/v1/api-keys \
  -H "Authorization: Bearer sk_live_your_api_key"

Revoking Keys

curl -X POST https://api.adteco.com/v1/api-keys/key_123/revoke \
  -H "Authorization: Bearer sk_live_your_api_key"

Error Responses

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked",
    "status": 401
  }
}

Missing API Key

{
  "error": {
    "code": "missing_authorization",
    "message": "No API key provided in Authorization header",
    "status": 401
  }
}

Insufficient Permissions

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key does not have permission to perform this action. Required scope: documents:write",
    "status": 403
  }
}

Rate Limiting

API keys are subject to rate limits based on your plan:

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1700000000

Webhook Authentication

When using webhooks, verify requests came from Adteco by checking the signature:

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
const signature = req.headers['x-docextract-signature'];
const isValid = verifyWebhookSignature(
  req.body,
  signature,
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Need Help?

• Dashboard: Manage API keys
• Email: support@adteco.com
• Documentation: API Reference