Copy page

API Guides

Authentication Guide

All API Codex APIs authenticate with a single API key. One key works across all 40 APIs, comes with free monthly credits, and takes less than a minute to create.

Getting Your Key

1. Sign up at dash.apicodex.io with just your email, no credit card required
2. Create an API key from the API Keys page
3. That's it: the key (acx_live_...) works across all 40 APIs and includes 1,000 free credits every month

Making Requests

Call any API at https://api.apicodex.io and pass the key either as an apikey query parameter or an X-Api-Key header:

Code
GET https://api.apicodex.io/dns-lookup/v1/check?name=example.com&apikey=YOUR_API_KEY

Code
GET https://api.apicodex.io/dns-lookup/v1/check?name=example.com
X-Api-Key: YOUR_API_KEY

Implementation Examples

cURL

Code
curl "https://api.apicodex.io/countries/v1/code/TR" \
  -H "X-Api-Key: $APICODEX_KEY"

JavaScript/Node.js

Code
const response = await fetch(
  'https://api.apicodex.io/email-intelligence/v1/check?email=jane@startup.io',
  { headers: { 'X-Api-Key': process.env.APICODEX_KEY } }
);
const data = await response.json();

Python

Code
import os
import requests

response = requests.get(
    'https://api.apicodex.io/email-intelligence/v1/check',
    headers={'X-Api-Key': os.environ['APICODEX_KEY']},
    params={'email': 'jane@startup.io'},
)
data = response.json()

PHP

Code
$curl = curl_init('https://api.apicodex.io/dns-lookup/v1/check?name=example.com');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('APICODEX_KEY')],
]);
$response = json_decode(curl_exec($curl), true);

Credits and Quotas

Every request costs a fixed number of credits depending on the API: bundled-data APIs cost 1 credit, live network lookups 5, and AI or scraping APIs 25. Your plan's monthly credit quota, per-key usage, and billing all live in the dashboard. Only successful (2xx) responses consume credits.

Security Best Practices

1. Never Expose Keys in Client-Side Code

❌ Bad Practice:

Code
// Never do this in frontend code
const API_KEY = 'acx_live_a1b2c3d4...'; // Exposed to users!

✅ Good Practice:

Code
// Backend proxy endpoint
app.post('/api/dns-lookup', async (req, res) => {
  const response = await fetch(apiUrl, {
    headers: { 'X-Api-Key': process.env.APICODEX_KEY }, // Server-side only
  });
  res.json(await response.json());
});

2. Use Environment Variables

.env file:

Code
APICODEX_KEY=your_actual_api_key_here

Load it with dotenv (Node.js), python-dotenv (Python), or your framework's config layer, and add .env to .gitignore.

3. Rotate Keys When Needed

You can keep up to 5 active keys in the dashboard: create a new key, switch your deployment over, then revoke the old one. Revocation takes effect within about a minute.

4. Secure Storage in Production

• AWS: AWS Secrets Manager or Parameter Store
• Azure: Azure Key Vault
• Google Cloud: Secret Manager
• Heroku: Config Vars
• Vercel / Cloudflare: Environment Variables
• Docker: Docker Secrets

Authentication Errors

Error Code	Description	Solution
401	Invalid, missing, or revoked API key	Check the key in the dashboard
429	Monthly credit quota reached	Upgrade your plan or wait for renewal
503	Service temporarily unavailable	Retry with exponential backoff

Error Handling Example

Code
if (!response.ok) {
  switch (response.status) {
    case 401: throw new Error('Invalid or revoked API key');
    case 429: throw new Error('Credit quota exceeded');
    default: throw new Error(`Error: ${response.status}`);
  }
}

Testing Authentication

Code
# Test your API Codex key with curl (Countries API costs 1 credit)
curl "https://api.apicodex.io/countries/v1/code/TR?apikey=YOUR_API_KEY"

A JSON payload means you're authenticated; a 401 means the key is missing, mistyped, or revoked.

Troubleshooting

1. ✓ Verify the API key is correct (no extra spaces or characters)
2. ✓ Check key status and remaining credits in the dashboard
3. ✓ Ensure the header (X-Api-Key) or query param (apikey) is properly formatted
4. ✓ Verify the API endpoint URL is correct
5. ✓ Ensure you're not exceeding your plan's rate limit
6. ✓ Verify network connectivity and firewall settings

Next Steps

• Review Rate Limiting to understand usage limits
• Learn about Error Handling for robust applications
• Check Best Practices for production deployments
• Explore our API Catalog to start building

Need Help?

• Dashboard: Manage keys, usage, and billing at dash.apicodex.io
• API Codex Support: Contact us for API-specific questions
• Documentation: Browse our comprehensive guides