Holidays Authentication: API Key Setup & Security (2026)

Authentication overview

The Holidays API utilizes API keys as its primary method for authentication. An API key is a unique token that identifies the calling application and authorizes its access to the API's resources, such as public, school, and bank holiday data. All requests to the Holidays API must include a valid API key to ensure that only authorized entities can consume the service. This approach is common for RESTful APIs providing data access, offering a balance of simplicity for developers and necessary security for data providers Google Cloud API key best practices. The API key must be transmitted securely with each request, typically as a query parameter or an HTTP header.

Authentication is a critical component for developers integrating the Holidays API into their applications, providing a mechanism for usage tracking, rate limiting, and access control. Without proper authentication, API requests will be rejected, returning an HTTP 401 Unauthorized status code. The API's design prioritizes ease of integration while maintaining secure access to its global holiday datasets.

Supported authentication methods

Holidays exclusively supports API key authentication. This method involves generating a unique key from the Holidays developer dashboard and including it with every API request. The API key serves as both an identifier and a credential, allowing the Holidays service to verify the origin and authorization level of each incoming request. The simplicity of API keys makes them suitable for a wide range of applications, from server-side integrations to client-side scripts, provided proper security measures are implemented.

The following table outlines the authentication method supported by the Holidays API:

Developers should always transmit API keys over HTTPS to prevent interception. While API keys are simpler to implement than more complex protocols like OAuth 2.0, their security relies heavily on how they are stored and transmitted. For applications requiring granular permissions or user delegation, a system built on top of API keys might be necessary, though Holidays's current offering focuses on direct API key access to its holiday data endpoints.

Getting your credentials

To obtain an API key for the Holidays API, you must first register for an account on the Holidays platform. The process typically involves creating an account, which grants access to a developer dashboard where API keys can be generated and managed. This dashboard is the central point for developers to monitor their API usage, manage subscriptions, and generate new keys or revoke existing ones.

The general steps to acquire your API key are:

1. Sign Up/Log In: Navigate to the Holidays homepage and create a new account or log in to an existing one.
2. Access Dashboard: Once logged in, locate the developer dashboard or API settings section. This is usually accessible via a link like "Dashboard" or "API Keys" in the user menu.
3. Generate API Key: Within the API settings, there will be an option to generate a new API key. Follow the on-screen prompts. The system will typically generate a long, alphanumeric string.
4. Securely Store Key: Copy the generated API key immediately and store it in a secure location. It is crucial to treat your API key like a password. Do not hardcode it directly into client-side code that could be publicly exposed (e.g., frontend JavaScript).
5. Configure Application: Use the copied API key in your application to authenticate requests to the Holidays API.

Holidays offers a free tier that allows up to 500 requests per month, which also requires an API key for access. Paid plans, starting at $19/month for 5,000 requests, utilize the same API key authentication mechanism but provide higher rate limits and additional features.

Authenticated request example

Authenticating requests to the Holidays API involves including your API key in the request. The most common method is to pass it as a query parameter named apiKey. All requests must be made over HTTPS to ensure the API key is encrypted during transmission.

Here is an example using curl to fetch public holidays for a specific country and year, demonstrating how to include the API key:

curl -X GET \
  'https://api.holidays.app/v1/holidays?country=US&year=2026&apiKey=YOUR_API_KEY' \
  -H 'Accept: application/json'

In this example:

• https://api.holidays.app/v1/holidays is the base endpoint for retrieving holiday data.
• country=US specifies the United States as the target country for holiday data.
• year=2026 specifies the year for which holidays are requested.
• apiKey=YOUR_API_KEY is where you replace YOUR_API_KEY with the actual API key obtained from your Holidays developer dashboard.
• -H 'Accept: application/json' is an HTTP header indicating that the client prefers a JSON response.

For more detailed examples across various programming languages and specific endpoint usage, refer to the official Holidays API reference documentation.

Security best practices

Securing your API keys is paramount to prevent unauthorized access to your Holidays API usage and potential misuse. Adhering to these best practices helps protect your application and maintain the integrity of your integrations:

• Keep API Keys Confidential: Never expose your API keys in publicly accessible code, such as client-side JavaScript, mobile applications (without proper obfuscation), or public repositories. Treat them as sensitive as passwords.
• Use Environment Variables: For server-side applications, store API keys in environment variables rather than hardcoding them directly into your source code. This practice makes it easier to manage keys across different deployment environments (development, staging, production) and reduces the risk of accidental exposure.
• Transmit Over HTTPS Only: Always ensure that all API requests are made over HTTPS (HTTP Secure). HTTPS encrypts the communication channel between your application and the Holidays API, protecting your API key from interception by malicious actors during transit. The Holidays API implicitly requires HTTPS for all endpoints.
• Restrict IP Addresses: If your application interacts with the Holidays API from a fixed set of IP addresses, check if the Holidays platform allows you to restrict API key usage to those specific IP addresses. This adds an extra layer of security, as even if an API key is compromised, it cannot be used from an unapproved location. Consult the Holidays documentation for this feature availability.
• Rotate API Keys Periodically: Regularly generate new API keys and revoke old ones. This practice, known as key rotation, minimizes the impact of a compromised key by limiting its active lifespan. The frequency of rotation depends on your security policies and risk assessment.
• Monitor API Usage: Regularly check your API usage metrics in the Holidays developer dashboard. Unusual spikes or patterns could indicate unauthorized use of your API key.
• Implement Server-Side Calls: Whenever possible, make API calls from your server-side application rather than directly from client-side code. This keeps your API key secure on your server and prevents it from being exposed in a user's browser or mobile app. If client-side calls are unavoidable, consider using a proxy server to append the API key securely.
• Understand Rate Limits: While not a direct security measure, understanding and respecting API rate limits (e.g., 500 requests/month for free tier, 5,000 requests/month for Starter tier) helps prevent your account from being flagged or temporarily blocked due to unusual activity, which could indirectly relate to security incidents.

Adhering to these security practices ensures that your integration with the Holidays API remains robust and protected against common vulnerabilities. For general best practices regarding API key management, developers can review resources like the IETF RFC 7235 on Authentication, which outlines fundamental principles for HTTP authentication schemes.