Authentication

AstroCal uses organization-scoped authentication. Every API request that accesses organization resources must include an X-Org-Id header.

Current Authentication

During the MVP phase, authentication uses the X-Org-Id header to identify your organization:

curl http://localhost:3000/v1/event_types \
  -H "X-Org-Id: YOUR_ORG_ID"

Header Format

Public Endpoints

Some endpoints don't require authentication:

• GET /health — Health check
• POST /v1/bookings — Create a booking (public booking page)
• GET /v1/openapi.json — OpenAPI specification

Authenticated Endpoints

All other endpoints require the X-Org-Id header:

• GET/POST /v1/event_types — Manage event types
• GET/POST /v1/event_types/:id/availability_rules — Manage availability
• GET /v1/event_types/:id/availability — Check availability
• GET /v1/bookings — List bookings
• GET /v1/bookings/:id — Get booking details
• GET/POST /v1/calendars/* — Calendar connections

Error Responses

Missing or invalid authentication returns a 400 error:

{
  "error": {
    "code": "validation_error",
    "message": "X-Org-Id header is required"
  }
}

Future: API Keys

API key authentication (PRD-005) will add:

• Scoped API keys with rate limits
• Key rotation and revocation
• Per-key usage tracking

The X-Org-Id header will be replaced by bearer token authentication once API keys are implemented.