​
API Key Authentication

Byul REST API uses API key authentication. All requests must include a valid API key in the request headers.

​
Getting Your API Key

  1. Sign up at byul.ai
  2. Login to your API Dashboard
  3. Copy your API key (starts with byul_v2)
Your API key starts with the byul_ prefix and is immediately available after account creation.

​
Authentication Methods

Include your API key using the X-API-Key header: 
X-API-Key: byul_api_key

​
Example Requests

curl -X GET "https://api.byul.ai/api/v2/news" \
  -H "X-API-Key: byul_api_key"

​
Security Best Practices

​
Environment Variables

Secure (Recommended) 
# Set environment variable
export BYUL_API_KEY=byul_api_key

# Use in your application
const apiKey = process.env.BYUL_API_KEY;
Insecure (Don’t do this) 
// Never hardcode API keys in source code
const apiKey = 'byul_api_key';

​
Client-Side Security

Never expose API keys in client-side code. API keys should only be used on your backend servers.
Don’t expose in browser 
// This exposes your API key to all website visitors
const apiKey = 'byul_api_key';
fetch(`https://api.byul.ai/api/v2/news`, {
  headers: { 'X-API-Key': apiKey }
});
Use a backend proxy instead 
// Frontend makes request to your backend
const response = await fetch('/api/news');

// Backend handles API key authentication
app.get('/api/news', async (req, res) => {
  const response = await fetch('https://api.byul.ai/api/v2/news', {
    headers: { 'X-API-Key': process.env.BYUL_API_KEY }
  });
  res.json(await response.json());
});

​
Key Management

  1. Rotate Keys Regularly: Generate new API keys periodically
  2. Monitor Usage: Check your dashboard for unusual activity
  3. Restrict Access: Use separate keys for different environments
  4. Secure Storage: Store keys in secure environment variables or key management systems

​
Development Environments

Use different API keys for different environments: 
# Development
BYUL_API_KEY=byul_api_key

# Production  
BYUL_API_KEY=byul_api_key

​
Authentication Errors

​
401 Unauthorized

{
  "statusCode": 401,
  "message": "API key is required. Please provide a valid V2 API key in the X-API-Key header.",
  "error": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "path": "/api/v2/news"
}
Common causes:
  • Missing X-API-Key header
  • Invalid API key format
  • Expired or revoked API key

​
403 Forbidden

{
  "statusCode": 403,
  "message": "Feature not available on current plan",
  "error": "Forbidden",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "path": "/api/v2/news"
}
Common causes:
  • Plan doesn’t support the requested feature
  • Account suspended or payment overdue

​
402 Payment Required

{
  "statusCode": 402,
  "message": "Plan expired",
  "error": "Payment Required",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "path": "/api/v2/news"
}
Common causes:
  • Plan expired
  • Payment method failed
  • Usage exceeded plan limits

​
Testing Authentication

Use the health check endpoint to test your authentication: 
curl -X GET "https://api.byul.ai/api/v2/news/health" \
  -H "X-API-Key: byul_api_key"
Success response: 
{
  "status": "healthy",
  "hasData": true
}

​
Plan-Based Access

Different plans have different capabilities:
PlanRate LimitFeatures
Test (Free)30 req/minBasic news access
Starter ($19)60 req/minBasic news access
Pro ($99)120 req/minNews + WebSocket access
EnterpriseCustomAll features + custom development
Check your current plan and usage in the API Dashboard.

​
Next Steps

Make Requests

Learn about request structure and parameters

Handle Errors

Implement proper error handling and retries

Rate Limits

Understand rate limiting and optimization

Upgrade Plan

Increase your rate limits and access WebSocket