Getting Started

Copy page

Authentication Guide

All BotsKYC API requests require authentication using API keys managed through our Zuplo API gateway.

Getting Your API Key

Option 1: Self-Service Portal (Coming Soon)

Visit portal.botskyc.com to:

1. Create your account
2. Generate API keys
3. Manage your subscription
4. View usage analytics

Option 2: Contact Support

Email [email protected] to receive your API credentials.

Using Your API Key

Include your API key in the Authorization header of every request:

Code
 
curl https://api.botskyc.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Examples by Language

JavaScript/TypeScript

Code
 
const apiKey = process.env.BOTSKYC_API_KEY;

const response = await fetch('https://api.botskyc.com/v1/identity/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
});

Python

Code
 
import os
import requests

api_key = os.getenv('BOTSKYC_API_KEY')

response = requests.post(
    'https://api.botskyc.com/v1/identity/scan',
    headers={'Authorization': f'Bearer {api_key}'},
    files={'documents': open('id-card.jpg', 'rb')}
)

cURL

Code
 
curl -X POST https://api.botskyc.com/v1/identity/scan \
  -H "Authorization: Bearer $BOTSKYC_API_KEY" \
  -F "[email protected]"

Security Best Practices

Store Credentials Securely

❌ Never do this:

Code
 
// Don't hardcode API keys
const apiKey = "sk_live_abc123xyz";

✅ Do this instead:

Code
 
// Use environment variables
const apiKey = process.env.BOTSKYC_API_KEY;

Environment Variables

Create a .env file (and add to .gitignore):

Code
 
# .env
BOTSKYC_API_KEY=your_api_key_here
BOTSKYC_API_URL=https://api.botskyc.com

Load in Node.js:

Code
 
require('dotenv').config();
const apiKey = process.env.BOTSKYC_API_KEY;

Load in Python:

Code
 
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('BOTSKYC_API_KEY')

API Key Security Checklist

• ✅ Store keys in environment variables
• ✅ Add .env to .gitignore
• ✅ Rotate keys regularly
• ✅ Use different keys for development and production
• ✅ Restrict API key permissions to minimum required
• ✅ Monitor API key usage for anomalies
• ❌ Never commit keys to version control
• ❌ Never share keys via email or chat
• ❌ Never log API keys

Rate Limiting

API keys are subject to rate limits based on your subscription tier:

Tier	Requests/Minute	Requests/Day	Burst Limit
Free	10	100	20
Starter	100	1,000	200
Professional	1,000	10,000	2,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every API response includes rate limit information:

Code
 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1732449600

Handling Rate Limits

When you exceed rate limits, you'll receive a 429 Too Many Requests response:

Code
 
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit of 100 requests per minute",
  "retryAfter": 45
}

Best practices:

Code
 
async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Retrying after ${retryAfter}s`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

API Key Management

Rotating API Keys

To rotate your API key:

1. Generate a new API key in the portal
2. Update your application with the new key
3. Test the new key works correctly
4. Revoke the old key

Zero-downtime rotation:

Code
 
// Support multiple keys during rotation
const apiKeys = [
  process.env.BOTSKYC_API_KEY_NEW,
  process.env.BOTSKYC_API_KEY_OLD
];

async function callWithFallback(url, options) {
  for (const key of apiKeys) {
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${key}`
      }
    });
    
    if (response.status !== 401) {
      return response;
    }
  }
  
  throw new Error('All API keys invalid');
}

Multiple Environments

Use separate API keys for different environments:

Code
 
# .env.development
BOTSKYC_API_KEY=sk_test_abc123

# .env.production
BOTSKYC_API_KEY=sk_live_xyz789

Troubleshooting

401 Unauthorized

Problem: Invalid or missing API key

Solutions:

• Verify the API key is correct
• Check the Authorization header format: Bearer YOUR_KEY
• Ensure the key hasn't expired or been revoked
• Confirm you're using the correct environment key

403 Forbidden

Problem: Valid key but insufficient permissions

Solutions:

• Verify your subscription tier supports the endpoint
• Check if the API key has required permissions
• Contact support to upgrade your plan

API Key Not Working

Checklist:

1. Is the key in the correct format? Bearer sk_...
2. Are you using the production key for production API?
3. Has the key been revoked?
4. Is your subscription active?
5. Are you hitting the correct base URL? https://api.botskyc.com

Support

Need help with authentication?

• Email: [email protected]
• Documentation: developers.botskyc.com

---

Next Steps:

• Quick Start Guide - Make your first API call
• Rate Limits - Understand usage limits
• API Reference - Explore available endpoints