Sandbox Mode

AstroCal's sandbox mode lets you test your integration without creating real calendar events, sending emails, or charging credit cards. Test data is fully isolated from live data.

How It Works

Sandbox mode is activated by using a test API key (prefixed ac_test_). When you authenticate with a test key:

• Event types, bookings, and availability rules are tagged with is_test: true
• No Google Calendar events are created or queried
• No emails are sent (booking confirmations, cancellations, reschedules)
• No Stripe charges are created for paid event types
• Webhooks still fire with is_test: true in the payload, so you can test your webhook handlers
• Rate limits are tracked separately from live mode

Getting Started

1. Create a Test API Key

From the dashboard, create an API key. Test keys are prefixed with ac_test_:

ac_test_k1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Auto-Seeded Test Data

On your first request with a test key, AstroCal automatically creates:

• A "Test Event" event type (30 minutes, slug test-event)
• Weekday availability rules (Monday-Friday, 9am-5pm)

This lets you start testing immediately without manual setup.

3. Make API Calls

Use your test key exactly like a live key:

# List test event types
curl https://api.astrocal.dev/v1/event-types \
  -H "Authorization: Bearer ac_test_k1_your_test_key"

# Create a test booking
curl -X POST https://api.astrocal.dev/v1/bookings \
  -H "Content-Type: application/json" \
  -d '{
    "event_type_id": "YOUR_TEST_EVENT_TYPE_ID",
    "start_time": "2026-03-02T10:00:00Z",
    "invitee_name": "Test User",
    "invitee_email": "test@example.com",
    "invitee_timezone": "America/New_York"
  }'

Data Isolation

Test and live data are completely isolated:

Conflict detection is also isolated — test bookings only conflict with other test bookings for the same organization.

Response Headers

Every authenticated response includes the X-AstroCal-Mode header:

X-AstroCal-Mode: test

or

X-AstroCal-Mode: live

Use this header to verify which mode your integration is operating in.

Webhooks in Test Mode

Webhooks fire normally in sandbox mode, with one addition — the payload includes an is_test field:

{
  "event": "booking.created",
  "data": {
    "id": "booking_123",
    "status": "confirmed",
    "is_test": true
  },
  "is_test": true,
  "created_at": "2026-03-01T10:00:00Z"
}

Your webhook handler can use this flag to skip production side effects during testing.

Cleaning Up Test Data

Delete all test data for your organization:

curl -X DELETE https://api.astrocal.dev/v1/test-data \
  -H "Authorization: Bearer ac_test_k1_your_test_key"

Response:

{
  "deleted": {
    "bookings": 5,
    "availability_rules": 10,
    "event_types": 2
  }
}

This endpoint only works with test API keys. Calling it with a live key returns 400 Bad Request.

Dashboard Test Mode

The dashboard includes a test/live mode toggle in the sidebar. When test mode is active:

• A yellow "Test Mode" banner appears at the top of pages
• Event types, bookings, and activity logs show only test data
• The sidebar toggle shows the current mode

Switch between modes at any time — your test and live data remain independent.

Best Practices

1. Always test with sandbox first. Validate your integration before switching to live keys.
2. Test webhook handling. Webhooks fire in both modes, so verify your handler correctly processes test events.
3. Clean up periodically. Use DELETE /v1/test-data to reset your sandbox when needed.
4. Check the mode header. Verify X-AstroCal-Mode in responses to ensure you're hitting the right environment.