Authentication overview

Nager.Date's Public Holiday API uses API keys for authentication, a common method for controlling access to web services and managing usage according to different service tiers. An API key is a unique identifier that authenticates the user or application making a request to the API. Unlike more complex authentication schemes like OAuth 2.0, API keys are typically simpler to implement, making them suitable for applications that primarily need to consume data without complex user authorization flows.

When you make a request to the Nager.Date API, your API key is included as a query parameter. The API server then validates this key against its records. If the key is valid and associated with an active subscription or the free tier, the request is processed, and the relevant holiday data is returned. If the key is invalid, missing, or exceeds rate limits, the API will return an error status code, typically a 401 Unauthorized or 403 Forbidden response.

The primary purpose of the API key in the Nager.Date context is to:

  • Identify the caller: Determine which application or user is making the request.
  • Enforce rate limits: Ensure that usage adheres to the limits defined for your specific Nager.Date plan.
  • Track usage: Monitor API calls for billing and analytical purposes.
  • Prevent unauthorized access: Restrict access to legitimate users who have obtained a key.

While API keys offer simplicity, they inherently carry security considerations. Unlike tokens in OAuth 2.0, API keys alone do not provide identity delegation or granular scope management. Therefore, careful handling and adherence to security best practices are crucial to prevent unauthorized use of your API key and potential service disruption or exceeding your usage quotas.

Supported authentication methods

Nager.Date exclusively supports API key authentication for its Public Holiday API. This method is integrated directly into the request URL as a query parameter. There are no alternative authentication methods such as OAuth 2.0, Basic Authentication, orBearer Tokens supported by the Nager.Date API directly. The simplicity of API keys aligns with the API's focus on providing straightforward access to holiday data.

The API key is passed as a query parameter named apiKey in the request URL. For instance, a request might look like https://date.nager.at/api/v3/PublicHolidays/2026/US?apiKey=YOUR_API_KEY. This approach is common in APIs designed for public data consumption where the primary concern is usage control rather than complex user identity management.

Below is a summary of the authentication method:

Method When to Use Security Level
API Key (Query Parameter) Accessing public holiday data, managing rate limits, simple application integration. Moderate (requires careful key management to prevent exposure).

Developers should be aware that passing credentials directly in the URL query string can expose them in server logs, browser history, and HTTP referer headers. While HTTPS mitigates man-in-the-middle attacks, it does not prevent these logging exposures. Therefore, best practices dictate treating API keys as sensitive credentials and implementing measures to protect them from unintended disclosure, as outlined in the Security Best Practices section.

Getting your credentials

To obtain an API key for Nager.Date, you typically need to register an account on their official website. The process generally involves signing up, and then your API key will be made available through a developer dashboard or account settings page. Nager.Date provides a free tier that allows up to 500 requests per day, which also requires an API key.

  1. Visit the Nager.Date Homepage: Navigate to the Nager.Date website.
  2. Sign Up/Register: Look for a "Sign Up" or "Get Started" option. You will likely need to provide an email address and create a password.
  3. Access Developer Dashboard: After successful registration and login, you should be redirected to a dashboard or a section specifically for developers.
  4. Generate/Locate API Key: Within the developer dashboard, there will typically be an option to generate a new API key or view an existing one. Nager.Date provides a clear UI for this, often under a "My API Key" or "Settings" section.
  5. Copy Your API Key: Once generated, safely copy your API key. It is a long string of alphanumeric characters. This key is crucial for making authenticated requests.

For paid plans, which offer higher request limits (e.g., 10,000 requests/day for €15/month), the API key acquisition process remains the same, but your key will be associated with your chosen subscription level. Always refer to the official Nager.Date documentation for the most up-to-date and specific instructions on account creation and API key retrieval.

Authenticated request example

Once you have obtained your API key from the Nager.Date developer dashboard, you can include it in your API requests. The API key is passed as a query parameter named apiKey. Below are examples demonstrating how to make an authenticated request using common tools and programming languages.

HTTP GET Request (cURL)

This cURL command retrieves public holidays for the United States in 2026, including your API key:

curl -X GET "https://date.nager.at/api/v3/PublicHolidays/2026/US?apiKey=YOUR_API_KEY_HERE"

Replace YOUR_API_KEY_HERE with your actual API key.

C# Example

Nager.Date offers a .NET client library, which simplifies interaction. If not using the library, you can make HTTP requests directly:

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class NagerDateHolidayClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;

    public NagerDateHolidayClient(string apiKey)
    {
        _httpClient = new HttpClient();
        _apiKey = apiKey;
    }

    public async Task<string> GetPublicHolidays(int year, string countryCode)
    {
        string requestUri = $"https://date.nager.at/api/v3/PublicHolidays/{year}/{countryCode}?apiKey={_apiKey}";
        HttpResponseMessage response = await _httpClient.GetAsync(requestUri);

        response.EnsureSuccessStatusCode();
        string responseBody = await response.Content.ReadAsStringAsync();
        return responseBody;
    }

    public static async Task Main(string[] args)
    {
        string myApiKey = "YOUR_API_KEY_HERE"; // Replace with your actual API key
        NagerDateHolidayClient client = new NagerDateHolidayClient(myApiKey);
        
        try
        {
            string holidaysJson = await client.GetPublicHolidays(2026, "US");
            Console.WriteLine(holidaysJson);
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Error: {e.Message}");
        }
    }
}

Remember to replace "YOUR_API_KEY_HERE" with the API key obtained from your Nager.Date account. The official Nager.Date Swagger UI also provides an interactive way to test API calls directly in your browser, allowing you to input your API key and see immediate results.

Security best practices

API keys, while simple, require careful handling to prevent unauthorized access and potential abuse of your Nager.Date account. Adhering to security best practices is crucial, especially since the API key is passed directly in the URL query string, which can have implications for logging and visibility. The Mozilla Developer Network documentation on Authorization headers provides a general overview of secure credential handling, which can be adapted to API keys.

1. Never hardcode API keys in client-side code

Directly embedding your API key in client-side JavaScript or mobile application code makes it easily discoverable by anyone inspecting your application's source. Malicious actors could extract and misuse your key, leading to unauthorized usage and potential charges. Instead, proxy requests through a secure backend server.

2. Use environment variables for server-side applications

For backend applications, store your API key in environment variables rather than directly in your source code. This practice prevents the key from being committed to version control systems like Git and keeps it separate from your application logic. Most cloud platforms and containerization technologies support environment variables for sensitive data.

3. Implement a proxy server for client-side access

If your client-side application (e.g., a single-page app or mobile app) needs to access Nager.Date, route all API calls through your own secure proxy server. Your proxy server can then append the API key to the request before forwarding it to Nager.Date. This way, the API key is never exposed to the client, and you maintain full control over access policies and rate limiting.

4. Restrict API key usage

While Nager.Date's API keys may not offer granular restrictions like IP whitelisting or domain restrictions directly, you can implement these at your proxy server level. Configure your proxy to only allow requests from specific IP addresses or origins, adding an extra layer of security before the request reaches Nager.Date with your key.

5. Securely store API keys

When storing keys, whether in environment variables, configuration files, or secret management services, ensure they are protected. Use secure storage mechanisms provided by your operating system or cloud provider (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). Avoid storing keys in plain text files that are accessible to unauthorized users.

6. Monitor API usage

Regularly monitor your Nager.Date API usage through your account dashboard. Sudden spikes in usage or unexpected request patterns can indicate that your API key might have been compromised. Early detection allows you to revoke the key and investigate potential breaches quickly.

7. Rotate API keys periodically

Even with strict security measures, it's a good practice to rotate your API keys periodically. This involves generating a new key, updating your applications to use the new key, and then revoking the old one. This limits the window of exposure if a key is compromised without your immediate knowledge.

8. Use HTTPS for all communications

Always ensure all communications with the Nager.Date API are done over HTTPS. This encrypts the data in transit, protecting your API key and the holiday data from eavesdropping during transmission. Nager.Date enforces HTTPS for all API endpoints.

By implementing these practices, you can significantly reduce the risk of unauthorized access and ensure the secure and reliable operation of your applications relying on the Nager.Date Public Holiday API.