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
- Sign up at byul.ai
- Login to your API Dashboard
- 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:
Example Requests
curl
JavaScript
Python
PHP
curl -X GET "https://api.byul.ai/api/v2/news?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z" \
-H "X-API-Key: byul_api_key"
const response = await fetch('https://api.byul.ai/api/v2/news', {
headers: {
'X-API-Key': process.env.BYUL_API_KEY
}
});
import requests
response = requests.get(
'https://api.byul.ai/api/v2/news',
headers={'X-API-Key': os.getenv('BYUL_API_KEY')}
)
$response = file_get_contents('https://api.byul.ai/api/v2/news', false,
stream_context_create([
'http' => [
'header' => 'X-API-Key: ' . getenv('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;
// 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.
// 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 }
});
// 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
- Rotate Keys Regularly: Generate new API keys periodically
- Monitor Usage: Check your dashboard for unusual activity
- Restrict Access: Use separate keys for different environments
- 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"
}
- 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"
}
- 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"
}
- 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"
{
"status": "healthy",
"hasData": true
}
Plan-Based Access
Different plans have different capabilities:
| Plan | Rate Limit | Features |
|---|
| Test (Free) | 30 req/min | Basic news access |
| Starter ($19) | 60 req/min | Basic news access |
| Pro ($99) | 120 req/min | News + WebSocket access |
| Enterprise | Custom | All features + custom development |
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
