Skip to main content

​
API Key Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of every request. 
Authorization: Bearer your-api-key

​
Getting Your API Key

  1. Log in to your EnviaAI Dashboard
  2. Navigate to Developer Portal > API Keys
  3. Click Create New Key
  4. Give your key a descriptive name
  5. Copy and securely store your API key
Your API key is only shown once when created. Store it securely in an environment variable or secret manager.

​
API Key Best Practices

Use Environment Variables

Never hardcode API keys in your source code

Rotate Regularly

Rotate your API keys periodically for security

Use Separate Keys

Use different keys for development and production

Monitor Usage

Track API usage to detect unauthorized access

​
Example Request

import { EnviaAI } from '@enviaai/sdk';

// Using SDK (recommended)
const client = new EnviaAI({
  apiKey: process.env.ENVIAAI_API_KEY
});

// Or using fetch
const response = await fetch('https://api.enviaai.app/v1/instances', {
  headers: {
    'Authorization': `Bearer ${process.env.ENVIAAI_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

​
Rate Limits

API rate limits vary by plan. Rate limit information is included in response headers.

​
Rate Limit Headers

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit resets

​
Rate Limits by Plan

EndpointLimitWindow
Messages100 requestsper minute
Instances50 requestsper minute
Webhooks100 requestsper minute
General500 requestsper minute

​
Handling Rate Limits

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}
Implement exponential backoff in your application to handle rate limits gracefully.

​
Error Responses

​
Authentication Errors

StatusCodeDescription
401invalid_api_keyThe API key is invalid or has been revoked
401missing_api_keyNo API key was provided in the request
401expired_api_keyThe API key has expired
403insufficient_permissionsThe API key doesn’t have permission for this action

​
Example Error Response

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "requestId": "req_abc123"
  }
}

​
API Key Scopes

When creating an API key, you can specify scopes to limit its permissions:
ScopeDescription
messages:readRead message history and status
messages:writeSend messages
instances:readView instance information
instances:writeManage instances (connect, disconnect)
webhooks:readView webhook configurations
webhooks:writeCreate and manage webhooks
billing:readView billing and usage information
Keys without specified scopes have full access to all endpoints available on your plan.

​
Security Recommendations

  1. Never expose API keys in client-side code - API calls should be made from your backend server
  2. Use HTTPS - All API requests must be made over HTTPS
  3. Implement IP allowlisting - Restrict API access to known IP addresses (available on Pro and Enterprise plans)
  4. Monitor for anomalies - Set up alerts for unusual API usage patterns
  5. Revoke unused keys - Delete API keys that are no longer needed

​
Testing Your API Key

Verify your API key is working correctly: 
curl https://api.enviaai.app/v1/health \
  -H "Authorization: Bearer your-api-key"
Expected response: 
{
  "status": "ok",
  "authenticated": true,
  "plan": "pro",
  "rateLimits": {
    "messages": {
      "limit": 2000,
      "remaining": 1999
    }
  }
}