Skip to main content

Authentication

All API requests to ByteEngine must be authenticated using API Keys. This guide covers how to obtain, use, and manage your API keys securely.

API Keys​

ByteEngine uses API keys for authentication. API keys authenticate your application with the ByteEngine platform and determine what resources you can access.

Getting Your API Key​

  1. Sign in to the ByteEngine Console
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy and securely store your API key
Security Notice

API keys provide full access to your ByteEngine resources. Never share them publicly or commit them to version control.

Base URL​

All API requests should be made to:

https://api.byteengine.boolbyte.com/v1/api

Making Authenticated Requests​

Include your API key in the Authorization header using the Bearer token format:

Authorization: Bearer YOUR_API_KEY

Example Request​

curl -X GET https://api.byteengine.boolbyte.com/v1/api/fhir/servers \
  -H "Authorization: Bearer be_1234567890abcdef..." \
  -H "Content-Type: application/json"

Example with JavaScript SDK​

import { ByteEngine } from '@boolbyte/engine';

const client = new ByteEngine({
  apiKey: 'be_1234567890abcdef...'
});

// List AI workers
const workers = await client.workers.list();

Example with Fetch​

const response = await fetch('https://api.byteengine.boolbyte.com/v1/api/workers', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer be_1234567890abcdef...',
    'Content-Type': 'application/json'
  }
});

const workers = await response.json();

Example with Python​

import requests

headers = {
    'Authorization': 'Bearer be_1234567890abcdef...',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.byteengine.boolbyte.com/v1/api/workers',
    headers=headers
)

workers = response.json()

API Key Management​

Rotating Keys​

For security, regularly rotate your API keys:

  1. Generate a new API key in the Console
  2. Update your applications to use the new key
  3. Delete the old key once migration is complete

Key Permissions​

API keys inherit the permissions of your ByteEngine account. You can control access by:

  • Team roles - Assign different roles to team members
  • Resource access - Some resources may have additional access controls
  • Environment separation - Use different keys for development and production

Error Responses​

401 Unauthorized​

Returned when no API key is provided or the key is invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden​

Returned when the API key doesn't have permission for the requested resource:

{
  "error": {
    "code": "forbidden", 
    "message": "Insufficient permissions for this resource"
  }
}

Rate Limiting​

API requests are rate limited to ensure fair usage:

  • Standard limits: 1000 requests per minute per API key
  • Burst limits: Up to 100 requests in a 10-second window

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When rate limits are exceeded, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Security Best Practices​

Environment Variables​

Store API keys in environment variables, not in your code:

# .env file
BYTEENGINE_API_KEY=be_1234567890abcdef...
// Access in your application
const apiKey = process.env.BYTEENGINE_API_KEY;

Network Security​

  • Always use HTTPS for API requests
  • Validate SSL certificates in production
  • Consider using API gateways for additional security layers

Key Storage​

  • Use secure secret management systems in production
  • Avoid logging API keys
  • Implement key rotation policies
  • Monitor API key usage for anomalies

SMART on FHIR Authentication​

For FHIR server access, ByteEngine also supports SMART on FHIR OAuth2 flows. This is separate from API key authentication and is used for patient data access:

  • API Keys - Authenticate with the ByteEngine platform
  • SMART on FHIR - Authorize access to patient data in FHIR servers

See the Health Data Store Introduction for details on implementing SMART on FHIR authentication.

Next Steps​