Skip to main content

API Keys

API keys allow you to authenticate API requests from your code without using a username or password.

Creating an API Key​

  1. Navigate to Settings → Developer
  2. Click Create API Key
  3. Enter a descriptive name (e.g., Production Server, CRM Integration)
  4. Click Generate
  5. Copy the key immediately — it is only shown once

Key format​

dgl_1234567890abcdef1234567890abcdef

All DocGenLab API keys begin with the dgl_ prefix.

Using API Keys​

Include your key in the X-API-Key header on every request:

curl -X GET "https://api.docgenlab.com/api/v1/templates/" \
  -H "X-API-Key: dgl_your_key_here"

Example: Generate a document​

curl -X POST "https://api.docgenlab.com/api/v1/documents/" \
  -H "X-API-Key: dgl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "your-template-uuid",
    "input_json": {
      "customer_name": "Acme Corp",
      "amount": 1250.00
    },
    "output_format": "pdf"
  }'

Security Best Practices​

Do:

  • Store keys in environment variables (DOCGENLAB_API_KEY=dgl_...)
  • Use a separate key per environment (dev / staging / prod)
  • Set expiration dates on keys where possible
  • Rotate keys regularly

Don't:

  • Commit keys to Git
  • Share keys in Slack, email, or tickets
  • Embed keys in frontend/client-side code
# .env  (add to .gitignore — never commit!)
DOCGENLAB_API_KEY=dgl_your_key_here

Rate Limits​

API requests are rate-limited per organisation. When you exceed the limit you receive a 429 response:

{ "detail": "Rate limit exceeded. Try again later." }

The default limit is 60 requests/minute. Limits can be adjusted by contacting support.

Recommended handling:

import time, requests

def call_with_backoff(fn, max_retries=3):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code == 429:
            time.sleep(2 ** attempt)   # 1s, 2s, 4s
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Max retries exceeded")

Idempotency Keys​

For document generation requests you can pass an X-Idempotency-Key header to prevent duplicate documents if your request is retried:

curl -X POST "https://api.docgenlab.com/api/v1/documents/" \
  -H "X-API-Key: dgl_your_key_here" \
  -H "X-Idempotency-Key: invoice-INV-2024-001-acme" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "...", "input_json": {...}, "output_format": "pdf" }'
  • If the same idempotency key is sent again, DocGenLab returns the existing document instead of generating a new one.
  • Use a value that uniquely identifies the business event (e.g., invoice-{invoice_id}).
  • Failed documents (status: failed) are not cached — resending the same key will retry generation.

Revoking a Key​

  1. Go to Settings → Developer
  2. Find the key in the list
  3. Click Revoke
warning

Revoking is immediate and irreversible. All requests using that key will fail with 401 Unauthorized.

Examples​