Festivo Public Holidays Authentication: API Key Guide (2026)

Authentication overview

Festivo Public Holidays secures access to its Public Holiday API and ICS Calendar Feeds primarily through API key authentication. This method requires developers to include a unique API key with each request, allowing the Festivo Public Holidays service to verify the origin and authorization level of the incoming call. API keys are suitable for applications where client-side secrets are not feasible or where a simpler authentication mechanism is preferred over more complex token-based flows like OAuth 2.0. The API key acts as a secret token, identifying the calling application and associating it with a specific user account and its corresponding usage plan and permissions. All communications with the Festivo Public Holidays API are expected to occur over HTTPS to ensure the confidentiality and integrity of data in transit, protecting both the API key and the holiday data exchanged.

The Festivo Public Holidays API is designed to be consumed by various programming languages and environments, offering comprehensive documentation and code examples to facilitate integration. Developers can manage their API keys through the Festivo Public Holidays user dashboard, where keys can be generated, revoked, and monitored. This centralized management ensures that access can be controlled and audited effectively. The use of API keys aligns with common practices for RESTful APIs providing data access where direct user interaction for authorization is not required for every API call, making it efficient for server-to-server communication or backend services integrated with the Festivo Public Holidays platform.

Supported authentication methods

Festivo Public Holidays supports API key authentication as its primary method for securing access to its API endpoints. This method is widely adopted for its simplicity and effectiveness in controlling access to resources without requiring a full user authentication flow for every request. An API key is a unique string that developers obtain from their Festivo Public Holidays account and include in API requests to verify their identity and authorization to consume the service. The Festivo Public Holidays API expects the API key to be passed either as a query parameter or as a custom header in the HTTP request.

While API keys are straightforward, it's critical to treat them as sensitive credentials. Unlike OAuth 2.0, which provides delegated authorization and refresh tokens, API keys grant direct access, making their compromise a significant security risk. For enhanced security, developers should implement best practices such as storing keys securely, transmitting them over HTTPS, and avoiding embedding them directly into client-side code where they could be exposed. The Festivo Public Holidays documentation provides specific guidance on how to securely integrate API keys into various application architectures.

The following table summarizes the primary authentication method supported by Festivo Public Holidays:

For a detailed comparison of authentication methods, including when to choose API keys over OAuth, the Cloudflare API authentication overview provides further context on general API security practices.

Getting your credentials

To begin using the Festivo Public Holidays API, you will need to obtain an API key. This key serves as your primary credential for authenticating requests and is associated with your Festivo Public Holidays account and subscription plan. The process for generating and managing your API key is performed through the Festivo Public Holidays user dashboard.

1. Sign Up or Log In: First, navigate to the Festivo Public Holidays homepage and either sign up for a new account or log in to your existing one. A free Developer Plan is available, offering 5,000 requests per month, which is sufficient for initial testing and development purposes.
2. Access the Dashboard: Once logged in, you will be directed to your user dashboard. This dashboard is your central hub for managing your account, monitoring API usage, and accessing your API keys.
3. Locate API Keys Section: Within the dashboard, look for a section typically labeled "API Keys", "Developers", or "Settings". The exact naming may vary, but it will be clearly identifiable as the place to manage your API credentials.
4. Generate a New API Key: If you don't have an existing key, or wish to generate a new one for a different application, there will be an option to "Generate New Key" or "Create API Key". Upon clicking this, a unique alphanumeric string will be displayed. This is your API key.
5. Securely Store Your API Key: Immediately copy your newly generated API key and store it in a secure location. It is crucial to treat your API key like a password. Avoid hardcoding it directly into your source code, especially for publicly accessible client-side applications. Environment variables, secret management services, or secure configuration files are recommended for storing API keys in production environments. For more information on secure API key storage, consider reviewing best practices for managing AWS access keys securely, which shares similar principles for any API key.
6. Revoke and Regenerate (Optional): The dashboard also provides options to revoke existing API keys if they are compromised or no longer needed. You can then generate a new key to restore access. Regular rotation of API keys is a good security practice, especially for long-running applications.

Refer to the official Festivo Public Holidays documentation for the most up-to-date and specific instructions on API key management.

Authenticated request example

Once you have obtained your API key, you can use it to make authenticated requests to the Festivo Public Holidays API. The API key can typically be included in your request either as a query parameter or within a custom HTTP header. The Festivo Public Holidays API documentation specifies the preferred method, but generally, including it as a query parameter named api_key is a common approach for simpler integrations, while a custom header (e.g., X-API-Key or Authorization: Bearer with the key) is often used for more robust and secure implementations, especially in frameworks that handle headers more naturally.

Below are examples demonstrating how to make an authenticated request using the api_key query parameter in common programming languages. Replace YOUR_API_KEY with your actual Festivo Public Holidays API key and adjust the endpoint URL as needed based on the specific API call you intend to make (e.g., querying holidays for a specific country and year).

Example: Fetching Public Holidays for Germany in 2026

import requests

API_KEY = "YOUR_API_KEY" # Replace with your actual API key
COUNTRY = "DE" # Germany
YEAR = 2026

url = f"https://api.festivo.com/v1/holidays?api_key={API_KEY}&country={COUNTRY}&year={YEAR}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
    holidays_data = response.json()
    print(holidays_data)
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except Exception as err:
    print(f"An error occurred: {err}")

const API_KEY = "YOUR_API_KEY"; // Replace with your actual API key
const COUNTRY = "US"; // United States
const YEAR = 2026;

const url = `https://api.festivo.com/v1/holidays?api_key=${API_KEY}&country=${COUNTRY}&year=${YEAR}`;

fetch(url)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error("Error fetching holidays:", error));

<?php

$apiKey = "YOUR_API_KEY"; // Replace with your actual API key
$country = "FR"; // France
$year = 2026;

$url = "https://api.festivo.com/v1/holidays?api_key=" . $apiKey . "&country=" . $country . "&year=" . $year;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // Ensure HTTPS verification

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
} else {
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($http_code >= 400) {
        echo "HTTP Error: " . $http_code . " - " . $response;
    } else {
        $data = json_decode($response, true);
        print_r($data);
    }
}

curl_close($ch);

?>

These examples illustrate the basic structure of an authenticated request. For specific endpoint details, request parameters, and response formats, always consult the official Festivo Public Holidays API reference documentation.

Security best practices

Adhering to security best practices is essential when integrating with any API, especially when dealing with authentication credentials like API keys. While Festivo Public Holidays provides a simple and effective authentication mechanism, the security of your integration largely depends on how you handle your API key. Neglecting these practices can lead to unauthorized access to your account, potential abuse, and service interruptions.

• Keep API Keys Confidential: Treat your Festivo Public Holidays API key as a sensitive secret, similar to a password. Never hardcode it directly into publicly accessible client-side code (e.g., JavaScript in a web browser) or commit it to version control systems like Git without proper encryption or exclusion (e.g., using .gitignore).
• Use Environment Variables: For server-side applications, store your API key in environment variables rather than directly in your codebase. This allows you to manage credentials outside your application's source code, making it easier to rotate keys and preventing them from being exposed in code repositories.
• Secure Configuration Management: In more complex deployments, consider using a dedicated secret management service (e.g., AWS Secrets Manager, Google Cloud Secret Manager, HashiCorp Vault) to store and retrieve API keys. These services are designed to manage sensitive credentials securely and provide programmatic access to them when needed.
• Transmit Over HTTPS Only: Always ensure that all API requests to Festivo Public Holidays are made over HTTPS (HTTP Secure). HTTPS encrypts the communication channel, protecting your API key and data from interception and tampering during transit. Festivo Public Holidays enforces HTTPS for all API interactions, but it's your responsibility to ensure your client library or HTTP client also uses it.
• Restrict API Key Permissions (if applicable): While Festivo Public Holidays API keys generally grant access to public holiday data based on your subscription, if the service ever introduces more granular key permissions, always configure your keys with the minimum necessary privileges. This principle of least privilege limits the potential damage if a key is compromised.
• Regular Key Rotation: Periodically rotate your API keys. This means generating a new key, updating your applications to use the new key, and then revoking the old one. Regular rotation reduces the window of opportunity for a compromised key to be exploited.
• Monitor API Usage: Regularly check your Festivo Public Holidays dashboard for unusual API usage patterns. Spikes in requests or requests from unexpected geographical locations could indicate a compromised API key. Timely monitoring allows you to detect and respond to potential security incidents quickly.
• Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. Avoid leaking sensitive information (like the API key itself) in error messages that might be visible to end-users or logged insecurely.
• Review Access Logs: If Festivo Public Holidays provides access logs, review them regularly to identify any suspicious access patterns or unauthorized attempts to use your API key. These logs can be invaluable for forensic analysis in case of a security incident.

By diligently following these security best practices, you can significantly enhance the security posture of your integration with the Festivo Public Holidays API and protect your application and data from potential threats. For further insights into API security, the Kong API security best practices guide offers a broader perspective on protecting API endpoints.