Authentication

Demeterics uses API keys for programmatic access and Google OAuth2 for web UI authentication. All API requests require your Demeterics API key as a Bearer token.

Creating an API Key

1. Sign in to demeterics.com
2. Navigate to API Keys in the left sidebar
3. Click Create API Key
4. Give your key a descriptive name (e.g., "Production API", "Development", "CI/CD")
5. Copy your key immediately—it's only shown once

API keys start with dmt_ and look like: dmt_abc123def456...

Using Your API Key

Recommended: Authorization Header

curl -X POST https://api.demeterics.com/groq/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.3-70b-versatile", "messages": [{"role": "user", "content": "Hello!"}]}'

Legacy Options (Not Recommended)

For backwards compatibility, these formats are supported but not recommended for production:

X-API-Key Header:

curl -H "X-API-Key: dmt_your_api_key_here" https://api.demeterics.com/api/v1/status

Query Parameter (avoid in production—logs API keys in server logs):

curl "https://api.demeterics.com/api/v1/status?api_key=dmt_your_api_key_here"

Always prefer the Authorization: Bearer header for security best practices.

Authentication Modes

Demeterics supports three authentication modes for LLM reverse proxy endpoints:

1. Demeter-Managed Keys (Default)

Use only your Demeterics API key. We provide vendor API keys automatically and bill per-token via Stripe credits.

curl -X POST https://api.demeterics.com/groq/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.3-70b-versatile", "messages": [...]}'

Benefits:

• ✅ No vendor account needed
• ✅ Instant access to all providers
• ✅ Simple pay-per-token billing

2. BYOK (Bring Your Own Key)

Store your vendor API keys (Groq, OpenAI, Anthropic, Gemini) in Settings → API Keys. Demeterics will use your keys for API calls.

# Same request format - Demeterics automatically uses your stored vendor key
curl -X POST https://api.demeterics.com/groq/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.3-70b-versatile", "messages": [...]}'

Benefits:

• ✅ No credit charges (use your vendor billing)
• ✅ Full usage tracking and analytics
• ✅ BigQuery storage for compliance
• ✅ Export and reporting tools

3. Dual-Key Mode (Advanced)

Combine your Demeterics API key with a vendor key in a single Authorization header:

curl -X POST https://api.demeterics.com/groq/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key;gsk_vendor_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.3-70b-versatile", "messages": [...]}'

Format: Bearer dmt_YOUR_KEY;vendor_VENDOR_KEY

Use cases:

• Migration from direct vendor APIs to Demeterics
• Per-request vendor key selection
• Hybrid deployments

Verifying Your API Key

Check that your API key is valid:

curl https://api.demeterics.com/api/v1/status \
  -H "Authorization: Bearer dmt_your_api_key_here"

Success Response:

{
  "status": "ok",
  "project": "demeterics-api"
}

Error Response (invalid key):

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Security Best Practices

1. Never Expose API Keys

• ❌ Don't commit API keys to Git repositories
• ❌ Don't include API keys in client-side code (JavaScript, mobile apps)
• ❌ Don't log API keys in application logs
• ✅ Use environment variables or secret management systems

Good Example (Python):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.demeterics.com/groq/v1",
    api_key=os.environ["DEMETERICS_API_KEY"]  # From environment variable
)

2. Rotate Keys Regularly

• Create a new API key every 90 days
• Use descriptive names to track key usage
• Revoke old keys after migration

3. Use Separate Keys per Environment

• Production: One API key for prod deployments
• Staging: Separate key for staging/testing
• Development: Different key for local development
• CI/CD: Dedicated key for automated testing

4. Monitor Key Usage

• Review usage at demeterics.com/api-keys
• Set up credit balance alerts
• Investigate unexpected spikes

5. Revoke Compromised Keys Immediately

If an API key is exposed:

1. Go to API Keys in the Demeterics dashboard
2. Click Revoke next to the compromised key
3. Generate a new key
4. Update your applications

Web UI Authentication

The Demeterics web dashboard uses Google OAuth2 for authentication:

1. Visit demeterics.com
2. Click Sign in with Google
3. Authorize Demeterics to access your Google profile
4. Manage API keys, view interactions, and configure settings

Note: Web UI sessions are separate from API keys. You need both:

• Google OAuth2 for the web dashboard
• API keys for programmatic API access

Rate Limits

API key rate limits depend on your account tier:

Rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1609459200

If you exceed the rate limit, you'll receive a 429 Too Many Requests error. Implement exponential backoff:

import time
import random

def make_request_with_backoff(func, max_retries=5):
    for retry in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response

        # Exponential backoff: 1s, 2s, 4s, 8s, 16s
        wait_time = (2 ** retry) + random.uniform(0, 1)
        time.sleep(wait_time)

    raise Exception("Max retries exceeded")

HTTPS-Only Policy

All API requests must use HTTPS. HTTP requests are automatically upgraded to HTTPS.

# ✅ Good
curl https://api.demeterics.com/api/v1/status

# ❌ Bad (will be redirected)
curl http://api.demeterics.com/api/v1/status

Security headers enforced:

• Strict-Transport-Security: max-age=31536000
• Content-Security-Policy: default-src 'self'
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY

Troubleshooting

"Invalid API key" error

• Verify you copied the entire key (starts with dmt_)
• Check for extra whitespace or line breaks
• Ensure the key hasn't been revoked
• Try generating a new key

"Insufficient permissions" error

• Your API key may be restricted to specific endpoints
• Contact support to adjust permissions

"Credit balance insufficient" error

• Add credits at demeterics.com/credits
• Or switch to BYOK mode (Settings → API Keys)

"Rate limit exceeded" error

• Implement exponential backoff
• Upgrade to a higher tier
• Contact support for custom limits

Need Help?

• Documentation: demeterics.com/docs
• Support: support@demeterics.com
• Dashboard: demeterics.com/api-keys

Next Steps: Learn how to make your first API call in the Quick Start Guide.