Authentication

All requests to the Festivo API require authentication using an API key.

Base URL

https://api.getfestivo.com/v3

Getting Your API Key

1. Sign up for a free account
2. Navigate to your dashboard
3. Copy your API key from the API Keys section

Free tier: Start with 100 requests/day, no credit card required.

Using Your API Key

Include your API key in every request using the X-API-Key header (recommended):

X-API-Key: YOUR_API_KEY

Alternative (deprecated): You can also use the api_key query parameter for legacy compatibility:

?api_key=YOUR_API_KEY

Important: The X-API-Key header method is recommended for:

• Better security (not exposed in URLs/logs)
• Cleaner URLs
• Standard REST API practices

1curl -H "X-API-Key: $FESTIVO_API_KEY" "https://api.getfestivo.com/v3/public-holidays/list?country=US&year=2026"

Security Best Practices

Keep Your API Key Secret

• Never commit API keys to version control
• Don't expose API keys in client-side code
• Use environment variables to store API keys

1# .env file
2FESTIVO_API_KEY=your_api_key_here

Rotate Keys Regularly

Rotate your API keys periodically for security:

1. Generate a new API key in your dashboard
2. Update your applications with the new key
3. Revoke the old key once migration is complete

Use Server-Side Requests

Always make API calls from your backend server, not from client-side JavaScript. This prevents exposing your API key to end users.

Rate Limiting

Your API key has rate limits based on your plan:

Rate limit information is returned in response headers:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99543
X-RateLimit-Reset: 1640995200

Authentication Errors

401 Unauthorized

Returned when your API key is missing or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing api_key query parameter"
  }
}

Solution: Check that your API key is correct and included as the api_key query parameter.

403 Forbidden

Returned when your API key doesn't have access to a specific endpoint:

{
  "error": {
    "code": "forbidden",
    "message": "Your plan does not include access to this endpoint"
  }
}

Solution: Upgrade your plan to access premium features.

429 Too Many Requests

Returned when you've exceeded your rate limit:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retry_after": 3600
  }
}

Solution: Wait until your rate limit resets or upgrade your plan.

Next Steps

• Quick Start Guide
• API Reference
• View Pricing Plans