Authentication

Authentication

All EnvoyX API requests are authenticated using API keys. You create and manage API keys through the EnvoyX Dashboard.

API Key Authentication

Creating an API Key

1. Log in to the EnvoyX Dashboard
2. Navigate to Settings > API Keys
3. Click Create New Key
4. Enter a descriptive name (e.g., "Production Server", "Staging Environment")
5. Copy the key immediately

Using API Keys

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

curl -X POST https://staging-api.tryenvoyx.com/api/v1/invoices/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

const apiKey = process.env.ENVOYX_API_KEY

const response = await fetch('https://staging-api.tryenvoyx.com/api/v1/invoices/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
  },
  body: formData,
})

const data = await response.json()

import os
import requests

api_key = os.getenv('ENVOYX_API_KEY')

with open('invoice.pdf', 'rb') as file:
    response = requests.post(
        'https://staging-api.tryenvoyx.com/api/v1/invoices/upload',
        headers={'X-API-Key': api_key},
        files={'file': file}
    )

data = response.json()

Security Best Practices

1. Use environment variables: Never hardcode API keys in source code
2. Rotate regularly: Create new keys and delete old ones periodically
3. Use descriptive names: Identify keys by server or environment
4. Limit scope: Create separate keys for different services
5. Monitor usage: Track which keys are being used and when
6. Delete unused keys: Remove keys for decommissioned services
7. Never expose in client-side code: API keys should only be used server-side

Rate Limits

API requests are rate-limited per API key:

Error Responses

401 — Missing API Key

Returned when no API key is provided:

{
  "success": false,
  "status": 401,
  "code": "MISSING_API_KEY",
  "message": "API key is required. Include it in the X-API-Key header."
}

403 — Invalid or Expired API Key

Returned when the API key is invalid, revoked, or expired:

{
  "success": false,
  "status": 403,
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked."
}

429 — Rate Limit Exceeded

Returned when you've exceeded the rate limit:

{
  "success": false,
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again later.",
  "data": {
    "retry_after": 60
  }
}

Implement exponential backoff or use the retry_after value to wait before retrying.

Next Steps

• Upload your first invoice
• Set up webhooks
• Connect via WebSocket