Authentication

AvailEngine uses API keys for all API access. JWT tokens are used internally by the dashboard.

Registration

Register as a developer through the dashboard or programmatically:

curl -X POST https://api.availengine.com/v1/auth/developer/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Smith"
  }'

This creates a Supabase Auth user with app_metadata.role = "developer". You can then create businesses via the Developer API.

API Keys

API keys are how your application authenticates with AvailEngine. Every request must include an Authorization header with a Bearer token.

Key Format

Prefix	Environment
avail_live_	Production
avail_test_	Sandbox / test

Authorization: Bearer avail_live_abc123def456...

Key Scopes

Each API key has scopes that control what it can do:

Scope	Permissions
read	GET requests — availability, bookings, business info
write	POST/PATCH/DELETE — create bookings, update resources, manage keys

Create keys with only the scopes they need. A public booking widget only needs read and write.

Rate Limiting

Each key has a configurable RPM (requests per minute). Default: 60. Exceeded requests return 429 with a Retry-After header.

Key Management

API keys are managed through the dashboard or the Management API:

# Create a key
curl -X POST https://api.availengine.com/v1/manage/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Widget key", "scopes": ["read", "write"], "rate_limit_rpm": 120}'

# List keys
curl https://api.availengine.com/v1/manage/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

# Revoke a key
curl -X DELETE https://api.availengine.com/v1/manage/api-keys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

The full API key is only returned once, at creation. Store it securely — it cannot be retrieved later.

JWT (Dashboard)

The developer dashboard uses Supabase Auth for login. The JWT's app_metadata contains the user's role and business_id (for business owners).

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

When both an API key and JWT are present, the API key takes priority.

Middleware Order

Every request passes through this chain:

Security Headers → CORS → Idempotency →
API Key Rate Limit → Billing Enforcement (402) → Usage Tracking

• Idempotency: POST/PATCH with Idempotency-Key header are deduplicated within 24 hours
• Billing Enforcement: Past-due developers get 402 Payment Required
• Usage Tracking: Every authenticated request is logged for metering