API Authentication

Docs

API Authentication

Complete guide to authenticating with the Evon API using API keys.

The Evon API uses API key authentication to secure all endpoints. This guide covers how to obtain, use, and manage your API keys.

Getting Started

1. Obtain Your API Key

Log into Dashboard: Sign in to your Evon dashboard
Navigate to Settings: Go to Settings → API Keys
Generate Key: Click "Generate New API Key"
Copy Key: Copy your API key immediately (it won't be shown again)
Store Securely: Store your API key in a secure location

2. Making Authenticated Requests

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

curl -X GET "https://dev.api.evoncrm.com/organization" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

API Key Management

Key Security Best Practices

Never commit API keys to version control
Use environment variables for API keys
Rotate keys regularly (every 90 days recommended)
Use different keys for different environments
Revoke unused or compromised keys immediately

Environment Variables

Store your API key in environment variables:

# .env file
EVON_API_KEY=your_api_key_here

// Node.js example
const apiKey = process.env.EVON_API_KEY;

# Python example
import os
api_key = os.getenv('EVON_API_KEY')

Authentication Examples

JavaScript/Node.js

const EVON_API_KEY = process.env.EVON_API_KEY;
const BASE_URL = 'https://dev.api.evoncrm.com';
 
async function makeAuthenticatedRequest(endpoint, options = {}) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'X-API-Key': EVON_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
 
  if (!response.ok) {
    throw new Error(`API request failed: ${response.status}`);
  }
 
  return response.json();
}
 
// Usage
const organization = await makeAuthenticatedRequest('/organization');

Python

import requests
import os
 
EVON_API_KEY = os.getenv('EVON_API_KEY')
BASE_URL = 'https://dev.api.evoncrm.com'
 
def make_authenticated_request(endpoint, method='GET', data=None):
    headers = {
        'X-API-Key': EVON_API_KEY,
        'Content-Type': 'application/json'
    }
 
    response = requests.request(
        method=method,
        url=f'{BASE_URL}{endpoint}',
        headers=headers,
        json=data
    )
 
    response.raise_for_status()
    return response.json()
 
# Usage
organization = make_authenticated_request('/organization')

PHP

<?php
$apiKey = $_ENV['EVON_API_KEY'];
$baseUrl = 'https://dev.api.evoncrm.com';
 
function makeAuthenticatedRequest($endpoint, $method = 'GET', $data = null) {
    global $apiKey, $baseUrl;
 
    $headers = [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ];
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
 
    if ($data) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
 
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
 
    if ($httpCode !== 200) {
        throw new Exception("API request failed: $httpCode");
    }
 
    return json_decode($response, true);
}
 
// Usage
$organization = makeAuthenticatedRequest('/organization');
?>

cURL

#!/bin/bash
 
EVON_API_KEY="your_api_key_here"
BASE_URL="https://dev.api.evoncrm.com"
 
# Function to make authenticated requests
make_request() {
    local endpoint=$1
    local method=${2:-GET}
    local data=$3
 
    if [ -n "$data" ]; then
        curl -X "$method" "$BASE_URL$endpoint" \
            -H "X-API-Key: $EVON_API_KEY" \
            -H "Content-Type: application/json" \
            -d "$data"
    else
        curl -X "$method" "$BASE_URL$endpoint" \
            -H "X-API-Key: $EVON_API_KEY" \
            -H "Content-Type: application/json"
    fi
}
 
# Usage
make_request "/organization"

Error Handling

Common Authentication Errors

401 Unauthorized - Missing API Key

{
  "error": "API key is required"
}

Solution: Include the X-API-Key header in your request.

401 Unauthorized - Invalid API Key

{
  "error": "Invalid API key"
}

Solution: Verify your API key is correct and hasn't been revoked.

403 Forbidden - Insufficient Permissions

{
  "error": "Insufficient permissions"
}

Solution: Contact support to verify your account permissions.

Handling Authentication Errors

async function handleApiResponse(response) {
  if (response.status === 401) {
    // Handle authentication errors
    console.error('Authentication failed. Check your API key.');
    // Redirect to login or refresh token
    return null;
  }
 
  if (response.status === 403) {
    // Handle permission errors
    console.error('Insufficient permissions for this operation.');
    return null;
  }
 
  if (!response.ok) {
    // Handle other errors
    const error = await response.json();
    throw new Error(`API Error: ${error.message}`);
  }
 
  return response.json();
}

Rate Limiting

Understanding Rate Limits

Limit: 100 requests per minute per API key
Window: Rolling 60-second window
Headers: Rate limit info included in response headers

Rate Limit Headers

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

Handling Rate Limits

async function makeRequestWithRetry(endpoint, options = {}, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(`${BASE_URL}${endpoint}`, {
        ...options,
        headers: {
          'X-API-Key': EVON_API_KEY,
          'Content-Type': 'application/json',
          ...options.headers,
        },
      });
 
      if (response.status === 429) {
        // Rate limited
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetTime ? (resetTime * 1000) - Date.now() : 60000;
 
        if (attempt < maxRetries) {
          await new Promise(resolve => setTimeout(resolve, waitTime));
          continue;
        }
      }
 
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

Testing Authentication

Verify API Key

Test your API key with a simple request:

curl -X GET "https://dev.api.evoncrm.com/organization" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -w "HTTP Status: %{http_code}\n"

Expected response:

HTTP Status: 200
{
  "name": "Your Organization",
  "email": "contact@yourorg.com",
  ...
}

Troubleshooting

Double-check API key: Copy-paste from dashboard
Verify header name: Must be exactly X-API-Key
Check environment: Ensure you're using the correct API key for your environment
Test with cURL: Isolate the issue by testing with cURL first

Overview Agents API