Authentication

ISAO API uses API key-based authentication with Bearer tokens. All API requests must include a valid API key in the Authorization header.

📋 Table of Contents

• Getting Your API Key
• Authentication Method
• API Key Types
• Permissions System
• Testing Authentication
• Security Best Practices

🔑 Getting Your API Key

1. Log in to your ISAO dashboard

2. Navigate to Settings → API Keys (/dashboard/settings/api-keys)

3. Click "Create New API Key"

4. Configure your key:

   • Name: Descriptive name (e.g., "Zapier Integration")
   • Description: Optional description
   • Service Type: Choose the appropriate type
   • Permissions: Select required permissions
   • Rate Limits: Set appropriate limits
   • Expiration: Optional expiration date

5. Copy the generated API key immediately (it won't be shown again)

🔐 Authentication Method

All API requests must include the API key in the Authorization header using the Bearer token format:

Authorization: Bearer YOUR_API_KEY_HERE

Example Request

curl -H "Authorization: Bearer ck_f98211064cbfc547bf3f1edc8c75da099d644be7c4ac52f49041953838bb3fc7" \
  https://staging.isao.io/api/external/contacts

Example with cURL

# Set your API key as an environment variable
export ISAO_API_KEY="ck_f98211064cbfc547bf3f1edc8c75da099d644be7c4ac52f49041953838bb3fc7"

# Use in requests
curl -H "Authorization: Bearer $ISAO_API_KEY" \
  https://staging.isao.io/api/external/test

🏷️ API Key Types

Choose the appropriate type when creating your API key:

Generic (generic)

• Use case: General purpose integrations
• Prefix: ck_
• Best for: Custom applications, testing

Zapier (zapier)

• Use case: Zapier workflows and automations
• Prefix: zap_
• Best for: Zapier integrations, REST hooks

Make (make)

• Use case: Make.com (ex-Integromat) scenarios
• Prefix: make_
• Best for: Make.com integrations

Webhook (webhook)

• Use case: Custom webhook integrations
• Prefix: whk_
• Best for: Real-time notifications

Custom (custom)

• Use case: Specialized integrations
• Prefix: cst_
• Best for: Enterprise applications

🛡️ Permissions System

API keys use a granular permission system. Grant only the permissions your integration needs:

Available Permissions

Permission	Description	Required For
contacts:read	Read contact information	Listing, searching, viewing contacts
contacts:write	Create and update contacts	Creating, updating contacts
deals:read	Read deal information	Listing, viewing deals
deals:write	Create and update deals	Creating, updating deals
agents:read	Read AI agent information	Listing agents
webhooks:read	View webhook subscriptions	Listing webhooks
webhooks:write	Manage webhook subscriptions	Creating, deleting webhooks

Permission Examples

// Read-only integration
{
  "permissions": ["contacts:read", "deals:read"]
}

// Full CRM integration
{
  "permissions": [
    "contacts:read", "contacts:write",
    "deals:read", "deals:write",
    "webhooks:read", "webhooks:write"
  ]
}

// Webhook-only integration
{
  "permissions": ["webhooks:write"]
}

✅ Testing Authentication

Test Endpoint

Use the test endpoint to verify your API key is working:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://staging.isao.io/api/external/test

Success Response

{
  "success": true,
  "message": "API key is valid and working",
  "data": {
    "companyId": "cmb72clgt0003145mvfrg8iyh",
    "permissions": ["contacts:read", "contacts:write"],
    "timestamp": "2024-11-08T09:30:00.000Z"
  }
}

Error Responses

Missing API Key

curl https://staging.isao.io/api/external/test

{
  "success": false,
  "error": "API key required in Authorization header",
  "message": "Please provide a valid API key in the format: Authorization: Bearer YOUR_API_KEY"
}

Invalid API Key

curl -H "Authorization: Bearer invalid_key" \
  https://staging.isao.io/api/external/test

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid, expired, or inactive"
}

Insufficient Permissions

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://staging.isao.io/api/external/contacts

{
  "success": false,
  "error": "Permission denied: contacts:read required",
  "message": "This API key does not have the required permission: contacts:read",
  "requiredPermission": "contacts:read",
  "availablePermissions": ["webhooks:write"]
}

🔒 Security Best Practices

1. Environment Variables

Never hardcode API keys in your source code:

// ❌ Bad
const apiKey = "ck_f98211064cbfc547bf3f1edc8c75da099d644be7c4ac52f49041953838bb3fc7";

// ✅ Good
const apiKey = process.env.ISAO_API_KEY;

2. Server-Side Only

API keys should only be used in server-side applications, never in client-side code (browser JavaScript, mobile apps).

3. HTTPS Only

All API requests must be made over HTTPS. HTTP requests will be rejected.

4. Key Rotation

Regularly rotate your API keys:

• Generate a new key
• Update your applications
• Delete the old key

5. Minimal Permissions

Grant only the permissions your integration actually needs. You can always add more permissions later.

6. Monitor Usage

Regularly check the API key usage logs in your dashboard to detect any suspicious activity.

7. Rate Limiting

Set appropriate rate limits on your API keys to prevent abuse:

• Per Hour: Recommended 1000-5000 requests
• Per Day: Recommended 10000-50000 requests

🔧 Integration Examples

Node.js/JavaScript

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://staging.isao.io/api/external',
  headers: {
    'Authorization': `Bearer ${process.env.ISAO_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Test authentication
async function testAuth() {
  try {
    const response = await client.get('/test');
    console.log('✅ Authentication successful:', response.data);
  } catch (error) {
    console.error('❌ Authentication failed:', error.response.data);
  }
}

Python

import os
import requests

class IsaoClient:
    def __init__(self):
        self.base_url = "https://staging.isao.io/api/external"
        self.api_key = os.getenv("ISAO_API_KEY")
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
    
    def test_auth(self):
        response = requests.get(f"{self.base_url}/test", headers=self.headers)
        response.raise_for_status()
        return response.json()

# Usage
client = IsaoClient()
result = client.test_auth()
print("✅ Authentication successful:", result)

PHP

<?php

class IsaoClient {
    private $baseUrl = 'https://staging.isao.io/api/external';
    private $apiKey;
    
    public function __construct() {
        $this->apiKey = getenv('ISAO_API_KEY');
    }
    
    private function makeRequest($method, $endpoint, $data = null) {
        $curl = curl_init();
        
        curl_setopt_array($curl, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json'
            ],
        ]);
        
        if ($data) {
            curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($curl);
        curl_close($curl);
        
        return json_decode($response, true);
    }
    
    public function testAuth() {
        return $this->makeRequest('GET', '/test');
    }
}

// Usage
$client = new IsaoClient();
$result = $client->testAuth();
echo "✅ Authentication successful: " . json_encode($result);
?>

❓ Troubleshooting

Common Issues

1. 401 Unauthorized: Check your API key format and validity
2. 403 Forbidden: Verify you have the required permissions
3. 429 Too Many Requests: You've hit rate limits, slow down your requests
4. 500 Internal Server Error: Contact support if persistent

Getting Help

If you encounter authentication issues:

• Check the Error Handling documentation
• Verify your API key in the dashboard
• Contact support at hello@isao.io