Authentication

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:

X-API-Key: byul_api_key

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;

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

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"
}

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:

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

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

Getting Started

News

Error Handling

Examples

Authentication

API Key Authentication

Getting Your API Key

Authentication Methods

Example Requests

Security Best Practices

Environment Variables

Client-Side Security

Key Management

Development Environments

Authentication Errors

401 Unauthorized

403 Forbidden

402 Payment Required

Testing Authentication

Plan-Based Access

Next Steps

Make Requests

Handle Errors

Rate Limits

Upgrade Plan

​API Key Authentication

​Getting Your API Key

​Authentication Methods

​Example Requests

​Security Best Practices

​Environment Variables

​Client-Side Security

​Key Management

​Development Environments

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​402 Payment Required

​Testing Authentication

​Plan-Based Access

​Next Steps

Make Requests

Handle Errors

Rate Limits

Upgrade Plan

API Key Authentication

Getting Your API Key

Authentication Methods

Example Requests

Security Best Practices

Environment Variables

Client-Side Security

Key Management

Development Environments

Authentication Errors

401 Unauthorized

403 Forbidden

402 Payment Required

Testing Authentication

Plan-Based Access

Next Steps