Iconus Tech/Documentation

Authentication

Learn how to authenticate with the Iconus Tech Check Fraud Prevention API using API Keys.

Overview

The Iconus Tech API uses API Key authentication for all requests. Every API call must include your API key in the x-api-key header.

Authentication Method: API Key (Header-based)
Header Name: x-api-key
Key Format: iconus_live_... or iconus_test_...

Getting Your API Key

Step 1: Register for an Account

Sign up at iconustech.com/auth/signup or use the API:

Register Partner
curl -X POST https://api.iconustech.com/v1/partners/register \
-H "Content-Type: application/json" \
-d '{
  "name": "Your Company",
  "email": "dev@yourcompany.com",
  "tier": "FREE"
}'

Response:

json
{
"success": true,
"data": {
  "partnerId": "partner_abc123",
  "apiKey": "iconus_live_xyz789abc123def456",
  "apiSecret": "secret_abc123...",
  "tier": "FREE",
  "requestLimit": 100,
  "rateLimit": 10,
  "status": "PENDING_APPROVAL"
}
}

Step 2: Save Your API Key

Important: Save your API key securely. You'll need it for all API requests.

  • ✅ Store in environment variables
  • ✅ Use a secrets manager (AWS Secrets Manager, HashiCorp Vault)
  • ✅ Never commit to version control
  • ✅ Rotate keys every 90 days

Using Your API Key

cURL Example

GET Request with API Key
curl https://api.iconustech.com/v1/checks/check_abc123 \
-H "x-api-key: YOUR_API_KEY"

JavaScript/Node.js

api-client.js
const API_KEY = process.env.ICONUS_API_KEY;
const BASE_URL = 'https://api.iconustech.com/v1';
 
async function getCheck(checkId) {
const response = await fetch(`${BASE_URL}/checks/${checkId}`, {
  headers: {
    'x-api-key': API_KEY,
  },
});
 
return response.json();
}
 
// Usage
const check = await getCheck('check_abc123');
console.log('Check:', check);

Python

api_client.py
import os
import requests
 
API_KEY = os.getenv('ICONUS_API_KEY')
BASE_URL = 'https://api.iconustech.com/v1'
 
def get_check(check_id):
  response = requests.get(
      f'{BASE_URL}/checks/{check_id}',
      headers={'x-api-key': API_KEY}
  )
  return response.json()
 
# Usage
check = get_check('check_abc123')
print('Check:', check)

PHP

api-client.php
<?php
$apiKey = getenv('ICONUS_API_KEY');
$baseUrl = 'https://api.iconustech.com/v1';
 
function getCheck($checkId) {
  global $apiKey, $baseUrl;
  
  $ch = curl_init("$baseUrl/checks/$checkId");
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "x-api-key: $apiKey"
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}
 
// Usage
$check = getCheck('check_abc123');
print_r($check);
?>

Environment Variables

Node.js / Next.js

.env.local
# Iconus Tech API Configuration
ICONUS_API_KEY=iconus_live_xyz789abc123def456
ICONUS_API_URL=https://api.iconustech.com/v1

Python

.env
# Iconus Tech API Configuration
ICONUS_API_KEY=iconus_live_xyz789abc123def456
ICONUS_API_URL=https://api.iconustech.com/v1

Loading Environment Variables

config.js
// Node.js with dotenv
require('dotenv').config();
 
const config = {
apiKey: process.env.ICONUS_API_KEY,
apiUrl: process.env.ICONUS_API_URL,
};
 
export default config;

Usage Tiers & Rate Limits

Partner accounts have different usage tiers with varying rate limits:

| Tier | Verifications/Month | Rate Limit | Price | |------|---------------------|------------|-------| | Free Starter | 100 | 10/min | $0 | | Pro | 5,000 | 100/min | $29/mo | | Business Enterprise | Unlimited | Custom | Contact Sales |

Rate Limit Headers

Every API response includes rate limit information:

json
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 2025-12-01T00:00:00Z
 
{
"success": true,
"data": { ... }
}

Handling Rate Limits

rate-limit-handler.js
async function makeRequest(url, options) {
const response = await fetch(url, options);
 
// Check rate limit headers
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');
 
if (response.status === 429) {
  console.error('Rate limit exceeded!');
  console.log(`Resets at: ${reset}`);
  throw new Error('Rate limit exceeded');
}
 
console.log(`Remaining requests: ${remaining}`);
return response.json();
}

Security Best Practices

1. Never Expose Your API Key

❌ DON'T:

  • Commit API keys to Git/GitHub
  • Hardcode keys in client-side JavaScript
  • Share keys in public forums or Slack
  • Use production keys in development

✅ DO:

  • Use environment variables
  • Store keys in secrets managers
  • Use different keys for dev/staging/prod
  • Rotate keys every 90 days

2. Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected.

Correct (HTTPS)
curl https://api.iconustech.com/v1/checks

3. Implement Retry Logic

retry-logic.js
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
  try {
    const response = await fetch(url, options);
    
    if (response.ok) {
      return response.json();
    }
    
    // Retry on 5xx errors
    if (response.status >= 500 && i < maxRetries - 1) {
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
      continue;
    }
    
    throw new Error(`HTTP ${response.status}`);
  } catch (error) {
    if (i === maxRetries - 1) throw error;
  }
}
}

4. Monitor Your Usage

Check your API usage regularly:

Check Usage
curl https://api.iconustech.com/v1/partners/partner_abc123 \
-H "x-api-key: YOUR_API_KEY"
json
{
"success": true,
"data": {
  "partnerId": "partner_abc123",
  "usageTier": "FREE",
  "requestCount": 87,
  "requestLimit": 100,
  "rateLimit": 10,
  "resetDate": "2025-12-01T00:00:00Z"
}
}

Error Handling

Authentication Errors

401 Unauthorized - Invalid or missing API key:

json
{
"error": "Unauthorized",
"message": "Invalid API key",
"statusCode": 401
}

Solution: Verify your API key is correct and active.

Rate Limit Errors

429 Too Many Requests - Rate limit exceeded:

json
{
"error": "Rate Limit Exceeded",
"message": "Rate limit exceeded",
"usage": {
  "current": 100,
  "limit": 100,
  "tier": "FREE"
},
"upgradeUrl": "https://iconustech.com/pricing",
"statusCode": 429
}

Solution: Wait for rate limit reset or upgrade your plan.

Handling Errors in Code

error-handling.js
async function makeApiRequest(endpoint) {
try {
  const response = await fetch(
    `https://api.iconustech.com/v1${endpoint}`,
    {
      headers: { 'x-api-key': process.env.ICONUS_API_KEY },
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 401) {
      throw new Error('Invalid API key');
    }
    
    if (response.status === 429) {
      throw new Error('Rate limit exceeded');
    }
    
    throw new Error(error.message);
  }
  
  return response.json();
} catch (error) {
  console.error('API Error:', error.message);
  throw error;
}
}

Testing Your Authentication

Test Your API Key

Test API Key
curl https://api.iconustech.com/v1/health \
-H "x-api-key: YOUR_API_KEY"

Expected Response:

json
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2025-11-12T10:30:00Z",
"architecture": "amplify-gen2"
}

Verify Rate Limits

Check Rate Limits
curl -I https://api.iconustech.com/v1/health \
-H "x-api-key: YOUR_API_KEY"

Look for these headers:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Next Steps

Support