Skip to main content

Authentication

Cortex uses API keys for authentication. This guide covers how to manage your keys securely and handle authentication in different environments.

🔑 API Key Management​

Getting Your API Key​

  1. Sign up at usecortex.co
  2. Navigate to your dashboard
  3. Generate a new API key
  4. Copy and store it securely

API Key Format​

cortex_sk_1234567890abcdef...
  • Prefix: cortex_sk_ (for secret keys)
  • Length: 64 characters total
  • Encoding: Base64 alphanumeric

🔐 Authentication Methods​

Use the Authorization header with Bearer token:

curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer cortex_sk_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

API Key Header (Alternative)​

You can also use the X-API-Key header:

curl -X POST https://api.usecortex.co/v1/search \
  -H "X-API-Key: cortex_sk_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

🛡️ Security Best Practices​

Environment Variables​

Never hardcode API keys. Use environment variables:

# .env file
CORTEX_API_KEY=cortex_sk_1234567890abcdef...
import os
from cortex import CortexClient

# Load from environment
api_key = os.getenv('CORTEX_API_KEY')
client = CortexClient(api_key=api_key)

Server-Side Only​

Client-Side Exposure

Never use API keys in client-side JavaScript, mobile apps, or any publicly accessible code.

❌ Don't do this:

// DON'T: Exposed in browser
const apiKey = 'cortex_sk_1234567890abcdef...';

✅ Do this instead:

// ✅ Proxy through your backend
const response = await fetch('/api/search', {
  method: 'POST',
  body: JSON.stringify({ query: 'AI developments' })
});

Key Rotation​

Rotate your API keys regularly:

  1. Generate a new key in dashboard
  2. Update your applications
  3. Test with new key
  4. Delete old key

🔍 Testing Authentication​

Quick Test​

# Test your key
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.usecortex.co/v1/auth/test

Success Response:

{
  "authenticated": true,
  "key_id": "key_abc123",
  "plan": "starter",
  "usage": {
    "requests_used": 45,
    "requests_limit": 2000,
    "reset_date": "2025-02-01T00:00:00Z"
  }
}

Common Auth Errors​

Error CodeDescriptionSolution
401Invalid API keyCheck key format and validity
403Rate limit exceededUpgrade plan or wait for reset
429Too many requestsImplement rate limiting

🏢 Enterprise Authentication​

SSO Integration​

Enterprise plans support Single Sign-On:

  • SAML 2.0
  • OpenID Connect
  • Active Directory

Contact enterprise@usecortex.co for setup.

IP Whitelisting​

Restrict API access to specific IP ranges:

{
  "allowed_ips": [
    "192.168.1.0/24",
    "10.0.0.0/8"
  ]
}

📊 Usage Monitoring​

Dashboard Metrics​

Monitor your API usage:

  • Request count (daily/monthly)
  • Success rate (% of successful calls)
  • Response time (average latency)
  • Error breakdown (by error type)

Programmatic Monitoring​

import cortex

client = cortex.CortexClient(api_key="your_key")

# Get usage stats
usage = client.get_usage()
print(f"Used: {usage.requests_used}/{usage.requests_limit}")

🔄 SDK Authentication​

Python SDK​

from cortex import CortexClient

# Method 1: Direct key
client = CortexClient(api_key="cortex_sk_...")

# Method 2: Environment variable
client = CortexClient()  # Reads CORTEX_API_KEY

# Method 3: Config file
client = CortexClient.from_config("~/.cortex/config.json")

JavaScript SDK​

import Cortex from '@cortex/sdk';

// Method 1: Direct key
const cortex = new Cortex({ apiKey: 'cortex_sk_...' });

// Method 2: Environment variable (Node.js)
const cortex = new Cortex(); // Reads process.env.CORTEX_API_KEY

🚨 Emergency Procedures​

Compromised Keys​

If your API key is compromised:

  1. Immediately revoke the key in dashboard
  2. Generate a new key
  3. Update all applications
  4. Monitor for unusual activity

Access Issues​

If you can't access your account:

  1. Password reset via email
  2. Contact support with account details
  3. Provide last 4 digits of API key

🆘 Support​

📋 Checklist​

Before going to production:

  • API key stored as environment variable
  • No hardcoded keys in code
  • Server-side authentication only
  • Monitoring and alerting set up
  • Key rotation schedule planned
  • Rate limiting implemented
  • Error handling in place

Next: First Request → - Learn request structure and parameters