Public Holidays API Authentication Methods (2026)

Authentication overview

The Public Holidays API provides access to holiday data for over 200 countries and regions, including country-specific, regional, and observed holidays. To ensure secure and authorized access to this data, the API employs an API key-based authentication system. This method allows developers to integrate holiday data into their applications while providing a mechanism for Public Holidays to manage and monitor API usage according to subscription plans, which include a free plan with 10,000 requests per month.

API keys serve as unique identifiers for your application when making requests to the Public Holidays API. They are essential for tracking usage, enforcing rate limits, and securing your data access. Without a valid API key, requests to protected endpoints will be rejected. Understanding the proper handling and security of your API key is crucial for maintaining the integrity and functionality of your integration.

The API documentation offers extensive examples in multiple popular languages, including JavaScript, PHP, Python, Ruby, and cURL, demonstrating how to incorporate the API key into your requests. This ensures developers can quickly get started regardless of their preferred programming environment.

Supported authentication methods

Public Holidays primarily utilizes a single, straightforward authentication method: API Key authentication. This approach is common for many web APIs due to its simplicity and ease of implementation. Developers integrate their unique API key directly into their API requests to gain access to the holiday data endpoints.

The API key functions as a token that verifies the identity of the requesting application against the Public Holidays service. It is associated with your user account and subscription plan, enabling the API to apply appropriate rate limits and access permissions. While simple, it is paramount to treat API keys as sensitive credentials, similar to passwords, to prevent unauthorized access.

The Public Holidays API does not currently support more complex authentication flows such as OAuth 2.0 or mutual TLS. The API key method is deemed sufficient for the typical use cases of retrieving public holiday data, prioritizing ease of development and rapid integration. For further details on API key security, refer to guides on securing API keys in cloud environments, which offer general best practices applicable to any API key implementation.

Authentication Methods Table

Getting your credentials

To obtain your Public Holidays API key, you will need to register for an account on the Public Holidays website. The process typically involves a few steps:

1. Sign Up: Navigate to the Public Holidays homepage and complete the registration process. This usually requires providing an email address and creating a password.
2. Verify Email: You may receive an email verification link to confirm your account.
3. Access Dashboard: Once registered and logged in, you will be directed to your personal dashboard or account settings page. This is where your API key will be displayed.
4. Locate API Key: Look for a section labeled "API Key", "Credentials", or "Settings". Your unique API key will be a string of alphanumeric characters.

It is important to store your API key securely and avoid hardcoding it directly into your application's source code, especially for client-side applications. Best practices suggest using environment variables or a secure configuration management system to manage your API key. The official Public Holidays documentation provides guidance on where to find and manage your API key within your account dashboard.

Authenticated request example

Authenticating with the Public Holidays API involves including your API key as a query parameter in your HTTP requests. Below are examples demonstrating how to make an authenticated request using cURL and Python, retrieving public holidays for a specific country and year.

cURL Example

This cURL command requests all public holidays for Germany in 2026. Replace YOUR_API_KEY with your actual API key.

curl "https://www.public-holidays.io/api/v1/holidays?key=YOUR_API_KEY&country=DE&year=2026"

In this example, key=YOUR_API_KEY is the query parameter that carries your authentication credential.

Python Example

This Python script performs the same request using the requests library. It's recommended to store your API key in an environment variable rather than directly in the code, as shown below.

import requests
import os

API_KEY = os.environ.get("PUBLIC_HOLIDAYS_API_KEY")

if not API_KEY:
    print("Error: PUBLIC_HOLIDAYS_API_KEY environment variable not set.")
    exit()

base_url = "https://www.public-holidays.io/api/v1/holidays"
params = {
    "key": API_KEY,
    "country": "DE",
    "year": 2026
}

try:
    response = requests.get(base_url, params=params)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

This Python example demonstrates how to pass the API key within the params dictionary, which requests then safely encodes into the URL's query string. The use of os.environ.get() for retrieving the API key from an environment variable is a critical security practice.

For more detailed examples across different languages and specific API endpoints, refer to the Public Holidays API reference documentation.

Security best practices

Securing your API key is paramount to prevent unauthorized access to your Public Holidays account and to avoid potential misuse, such as exceeding rate limits or incurring unexpected charges on paid plans. Adhering to these security best practices will help protect your integration:

• Do Not Hardcode API Keys: Avoid embedding your API key directly into your application's source code. This is especially critical for client-side applications where code can be easily inspected. Instead, use environment variables, secure configuration files, or a secrets management service. For instance, AWS Secrets Manager or Google Secret Manager can securely store and retrieve credentials.
• Restrict Access to API Keys: Limit who has access to your API keys. Only authorized personnel or automated systems should be able to retrieve and use them.
• Use HTTPS: Always ensure that all requests to the Public Holidays API are made over HTTPS. This encrypts the communication between your application and the API server, protecting your API key and the data exchanged from eavesdropping. The Public Holidays API endpoints are served exclusively over HTTPS.
• Implement Server-Side Calls: Whenever possible, make API calls from your server-side application rather than directly from client-side code (e.g., JavaScript in a web browser). Server-side environments offer a more controlled and secure way to manage and use API keys, as the key is never exposed to the end-user's browser.
• IP Whitelisting (if supported): While the Public Holidays API does not explicitly offer IP whitelisting as a feature for API keys, it's a general security practice to consider for APIs that do. If available, whitelisting allows you to specify a list of permitted IP addresses that can make requests using your API key, blocking requests from any other source.
• Monitor API Usage: Regularly check your Public Holidays account dashboard for API usage patterns. Unusual spikes in requests could indicate unauthorized use of your API key. Promptly investigate any suspicious activity.
• Rotate API Keys: Periodically rotate your API keys. If an API key is compromised, rotating it (i.e., generating a new one and revoking the old one) minimizes the window of vulnerability. Check your Public Holidays account settings for options to regenerate your API key.
• Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. This prevents your application from exposing sensitive information or crashing due to invalid credentials.

By following these best practices, developers can significantly enhance the security posture of their applications integrating with the Public Holidays API, safeguarding both their data and their account against potential threats. The Mozilla Developer Network's guide on API keys also provides general advice on secure usage.