Authentication

API Keys

API keys are issued per tenant and can have different access levels. Each key is a Bearer token that you include in the Authorization header of your requests.

Key Format

API keys follow this format:

kycg_1234567890abcdef1234567890abcdef

Creating API Keys

1. Log in to your KYC Genie dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Choose the owner (user who owns this key)
5. Give your key a descriptive name (e.g., "Production Server", "Development")
6. Optionally configure security features (IP whitelist, HMAC enforcement, API Scope and Expiration)
7. Copy and securely store your key (you won't be able to see it again)

Test vs Live Mode

KYC Genie supports two environments: Test and Live. Data created in one mode is completely isolated from the other.

Making Requests

All API requests must include your API key in the Authorization header using the Bearer scheme.

Example Request

curl https://kycgenie.com/api/v1/responses/ \
  -H "Authorization: Bearer kycg_1234567890abcdef" \
  -H "Content-Type: application/json"

import requests

headers = {
    'Authorization': 'Bearer kycg_1234567890abcdef',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://kycgenie.com/api/v1/responses/',
    headers=headers
)

print(response.json())

const response = await fetch('https://kycgenie.com/api/v1/responses/', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer kycg_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Required Headers

Idempotency

All mutating operations (POST, PUT, PATCH, DELETE) require an Idempotency-Key header to prevent duplicate requests from causing unintended side effects.

How It Works

1. Generate a unique key (UUID recommended) for each logical operation
2. Include it in the Idempotency-Key header
3. If you retry the request with the same key within 24 hours, you'll get the cached response
4. If you send the same key with different request data, you'll get a 409 Conflict error

Example with Idempotency

curl -X POST https://kycgenie.com/api/v1/responses/ \
  -H "Authorization: Bearer kycg_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "entity_name": "ACME Corp",
    "questionnaire_id": 123
  }'

import requests
import uuid

# Generate unique key for this operation
idempotency_key = str(uuid.uuid4())

response = requests.post(
    'https://kycgenie.com/api/v1/responses/',
    headers={
        'Authorization': 'Bearer kycg_1234567890abcdef',
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotency_key
    },
    json={
        'entity_name': 'ACME Corp',
        'questionnaire_id': 123
    }
)

# If network fails, retry with same key
if response.status_code == 500:
    # Same idempotency_key ensures no duplicate creation
    response = requests.post(..., headers={'Idempotency-Key': idempotency_key, ...})

import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4();

try {
  const response = await fetch('https://kycgenie.com/api/v1/responses/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer kycg_1234567890abcdef',
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      entity_name: 'ACME Corp',
      questionnaire_id: 123
    })
  });
  
  if (!response.ok) throw new Error('Request failed');
  
} catch (error) {
  // Safe to retry with same key - no duplicates will be created
  await fetch(url, { headers: { 'Idempotency-Key': idempotencyKey, ... } });
}

Idempotency Errors

API Key Security Features

When creating API keys, you can enable optional security features for enhanced protection.

IP Whitelisting

Restrict API key usage to specific IP addresses. Requests from non-whitelisted IPs will be rejected with 403 Forbidden.

{
  "name": "Production Server Key",
  "environment": "live",
  "ip_whitelist": ["203.0.113.0", "198.51.100.0/24"]
}

Scopes (Coming Soon)

Limit API key permissions to specific resources and operations.

HMAC Request Signing (Optional)

Require HMAC-SHA256 signatures on all requests for additional verification. When enabled, each request must include an X-Request-Signature header.

import hmac
import hashlib
import json

def sign_request(api_secret, method, path, body=None):
    """Generate HMAC signature for request"""
    # Combine method + path + body
    message = f"{method}{path}"
    if body:
        message += json.dumps(body, separators=(',', ':'), sort_keys=True)
    
    signature = hmac.new(
        api_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return signature

# Usage
signature = sign_request(
    api_secret='your_api_secret_from_settings',
    method='POST',
    path='/api/v1/responses/',
    body={'entity_name': 'ACME Corp', 'questionnaire_id': 123}
)

headers = {
    'Authorization': 'Bearer kycg_...',
    'X-Request-Signature': signature
}

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of requests.

Authentication Errors

Example Error Responses

Missing Idempotency Key

{
  "error": "missing_idempotency_key",
  "message": "Idempotency-Key header is required for POST/PUT/PATCH/DELETE requests",
  "status": 400
}

Idempotency Key Conflict

{
  "error": "idempotency_key_conflict",
  "message": "This idempotency key was already used with different request data",
  "status": 409
}

Invalid API Key

{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked",
  "status": 401
}

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits based on your subscription plan:

Rate Limit Headers

Every API response includes headers to help you track your usage:

Hourly Rate Limit

• X-RateLimit-Limit - Total requests allowed per hour
• X-RateLimit-Remaining - Requests remaining in current hour
• X-RateLimit-Reset - Seconds until the hourly limit resets

Burst Rate Limit (Per-Minute)

• X-RateLimit-Burst-Limit - Maximum requests per minute
• X-RateLimit-Burst-Remaining - Requests remaining this minute
• X-RateLimit-Burst-Reset - Seconds until the burst limit resets