Skip to main content

Authentication Guide

BotsKYC uses OAuth2 authentication to secure all API requests. This guide will walk you through getting your credentials and authenticating your requests.

🚀 Quick Start​

Step 1: Create Your Account​

  1. Visit the Developer Portal
  2. Click "Sign Up" (top right)
  3. Fill in your details:
    • Username
    • Password
    • First Name
    • Last Name
    • Email
  4. Click "Sign Up"
  5. You'll be logged in automatically

Step 2: Create an Application​

  1. After logging in, click "Applications" in the top menu
  2. Click "Add New Application"
  3. Fill in the details:
    • Name: Your application name (e.g., "My KYC App")
    • Per Token Quota: Select a tier (Bronze/Silver/Gold)
    • Description: Brief description of your app
  4. Click "Save"

Step 3: Subscribe to BotsKYC API​

  1. Click "APIs" in the top menu
  2. Find and click on "BotsKYC API"
  3. Click the "Subscribe" button
  4. Select:
    • Application: Choose the application you just created
    • Throttling Policy: Select your desired tier
  5. Click "Subscribe"

Step 4: Generate API Credentials​

  1. Go back to "Applications" and click on your application
  2. Click the "Production Keys" tab
  3. Click "Generate Keys"
  4. Important: Copy and save these credentials securely:
    • Consumer Key (Client ID)
    • Consumer Secret (Client Secret)
warning

Keep your credentials secure! Never commit them to version control or share them publicly.

🔐 Using Your Credentials​

Getting an Access Token​

Use the OAuth2 Client Credentials flow to get an access token:

curl -X POST https://api.botskyc.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJ4NXQiOiJNell4TW1Ga09HWXdNV...",
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3600
}

Making API Requests​

Include the access token in the Authorization header:

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

🔄 Token Management​

Token Expiration​

Access tokens expire after 1 hour (3600 seconds). Your application should:

  1. Store the token and expiration time
  2. Request a new token before the current one expires
  3. Handle 401 errors by refreshing the token

Token Refresh Best Practices​

// Example: Token management in JavaScript
class TokenManager {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Return cached token if still valid
    if (this.token && Date.now() < this.expiresAt) {
      return this.token;
    }

    // Get new token
    const response = await fetch('https://api.botskyc.com/oauth2/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    });

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + (data.expires_in * 1000) - 60000; // Refresh 1 min early

    return this.token;
  }
}

// Usage
const tokenManager = new TokenManager(
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET
);

const token = await tokenManager.getToken();

📊 Rate Limiting Tiers​

Different subscription tiers have different rate limits:

TierRequests/MinuteRequests/DayUse Case
Bronze101,000Testing & Development
Silver10050,000Small Production Apps
Gold1,000500,000Enterprise Applications
tip

Start with Bronze for testing, then upgrade to Silver or Gold for production.

🔒 Security Best Practices​

Store Credentials Securely​

❌ Don't do this:

// Never hardcode credentials
const clientId = "abc123xyz";
const clientSecret = "super-secret-key";

✅ Do this instead:

// Use environment variables
const clientId = process.env.BOTSKYC_CLIENT_ID;
const clientSecret = process.env.BOTSKYC_CLIENT_SECRET;

Environment Variables​

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

# .env
BOTSKYC_CLIENT_ID=your_client_id_here
BOTSKYC_CLIENT_SECRET=your_client_secret_here
BOTSKYC_API_BASE_URL=https://api.botskyc.com/v1

Rotate Credentials Regularly​

  1. Go to Developer Portal
  2. Navigate to your Application → Production Keys
  3. Click "Regenerate Secret"
  4. Update your application with new credentials

🧪 Testing Authentication​

Test your authentication setup:

#!/bin/bash

# Set your credentials
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# Get access token
echo "Getting access token..."
TOKEN_RESPONSE=$(curl -s -X POST https://api.botskyc.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET")

echo "Token Response: $TOKEN_RESPONSE"

# Extract token
ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)

echo "Access Token: $ACCESS_TOKEN"

# Test API call
echo -e "\nTesting API call..."
curl https://api.botskyc.com/v1/kyc/health \
  -H "Authorization: Bearer $ACCESS_TOKEN"

❓ Troubleshooting​

401 Unauthorized​

Cause: Invalid or expired token

Solution:

  1. Verify your credentials are correct
  2. Request a new access token
  3. Ensure you're using the correct token format: Bearer YOUR_TOKEN

403 Forbidden​

Cause: Valid token but insufficient permissions

Solution:

  1. Ensure you've subscribed to the BotsKYC API
  2. Check your subscription tier allows the operation
  3. Verify the API is published and available

Token Request Fails​

Cause: Invalid credentials or network issues

Solution:

  1. Double-check your Client ID and Secret
  2. Ensure you're using the correct token endpoint
  3. Verify network connectivity to api.botskyc.com

📞 Need Help?​

Next Steps​

✅ Credentials obtained and tested

Continue to: