Authentication overview

Authentication for the GurbaniNow API is a process that verifies the identity of a client application attempting to access its resources, which include Gurbani text, translations, and associated metadata. This mechanism ensures that only authorized applications can make requests to the API, protecting the integrity and availability of the service. Proper authentication is essential for managing API usage, enforcing rate limits, and securing sensitive data, even if the data itself is publicly available religious text. GurbaniNow specifically employs API keys as its primary method for authentication, which are unique identifiers assigned to each developer or application.

When an application sends a request to the GurbaniNow API, it must include a valid API key. The API then checks this key against its records to confirm that the request originates from a recognized and authorized source. This process is critical for maintaining the service's stability and ensuring fair usage across all developers, from those using the free personal use tier to those on paid subscription plans for higher request volumes. Understanding and correctly implementing API key authentication is the foundational step for any integration with GurbaniNow's services.

Supported authentication methods

The GurbaniNow API relies on API keys for authenticating client applications. This method is a common and straightforward approach for securing access to web services, especially for public data APIs where user-specific authentication (like OAuth 2.0) is not required for every individual end-user accessing the data through an application. An API key acts as a secret token that identifies the calling application or developer.

While API keys offer simplicity, it's important to differentiate them from more robust authentication protocols like OAuth 2.0, which is designed for delegated authorization, allowing users to grant third-party applications limited access to their resources without sharing their credentials. Given GurbaniNow's provision of publicly accessible religious scripture, an API key system is generally sufficient for managing access and usage at the application level rather than the end-user level. The API key ensures that all requests are traceable to a specific developer account, facilitating monitoring and enforcement of usage policies.

Authentication Method Comparison

Method When to Use Security Level
API Key Accessing GurbaniNow API endpoints, managing application-level access, tracking usage for billing and rate limiting. Moderate (relies on key secrecy, requires HTTPS)

Getting your credentials

To access the GurbaniNow API, you will need to obtain an API key. This key serves as your unique credential for authenticating requests. The process typically involves registering on the GurbaniNow developer portal and generating the key through your account dashboard.

Steps to obtain your API key:

  1. Register for a GurbaniNow Account: Navigate to the GurbaniNow website and sign up for a new developer account. This usually involves providing an email address and creating a password.
  2. Access the Developer Dashboard: Once registered and logged in, locate the developer or API section within your account dashboard. This area is specifically designed for managing your API integrations.
  3. Generate Your API Key: Within the API section, there should be an option to generate a new API key. Follow the on-screen prompts to create your key. It's common for platforms to allow you to name your keys for easier management, especially if you plan to use multiple keys for different applications.
  4. Securely Store Your Key: Upon generation, your API key will be displayed. It is crucial to copy this key immediately and store it in a secure location. Treat your API key like a password; do not embed it directly into client-side code, commit it to public version control, or share it unnecessarily.
  5. Understand Usage Tiers: Be aware of the GurbaniNow pricing summary, which outlines the request limits for the free personal use tier and details the paid tiers. Your API key will be associated with your account's chosen tier, determining your access limits.

If you encounter any issues during the key generation process or have questions about your account's API access, refer to the GurbaniNow API documentation or contact their support team for assistance.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests to GurbaniNow. The GurbaniNow API expects the API key to be sent as a header or a query parameter in your HTTP requests. Using headers is generally preferred for security reasons, as it keeps the key out of URL logs and browser history.

Example using a request header (recommended):

When sending your API key via a header, you would typically use a custom header name, such as x-api-key or Authorization with a custom scheme. Consult the GurbaniNow API reference for the exact header name they require. For this example, we'll assume a common header named X-GurbaniNow-API-Key.

JavaScript (using fetch):


const API_KEY = 'YOUR_GURBANINOW_API_KEY'; // Replace with your actual API key
const API_BASE_URL = 'https://api.gurbaninow.com';

async function getShabad(shabadId) {
  try {
    const response = await fetch(`${API_BASE_URL}/shabad/${shabadId}`, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'X-GurbaniNow-API-Key': API_KEY // Custom API key header
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error: ${response.status} - ${errorData.message || 'Unknown error'}`);
    }

    const data = await response.json();
    console.log(`Shabad ${shabadId}:`, data);
    return data;
  } catch (error) {
    console.error('Failed to fetch Gurbani data:', error);
    throw error;
  }
}

// Example usage: Fetch Shabad with ID 1
getShabad(1);

Example using a query parameter (less recommended for security):

While generally less secure than headers, API keys can sometimes be passed as query parameters. This method is simpler but exposes the key in URLs, which can be logged by servers, proxies, and browser histories.

JavaScript (using fetch):


const API_KEY = 'YOUR_GURBANINOW_API_KEY'; // Replace with your actual API key
const API_BASE_URL = 'https://api.gurbaninow.com';

async function getAng(angId) {
  try {
    const response = await fetch(`${API_BASE_URL}/ang/${angId}?apiKey=${API_KEY}`, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error: ${response.status} - ${errorData.message || 'Unknown error'}`);
    }

    const data = await response.json();
    console.log(`Ang ${angId}:`, data);
    return data;
  } catch (error) {
    console.error('Failed to fetch Gurbani data:', error);
    throw error;
  }
}

// Example usage: Fetch Ang with ID 10
getAng(10);

Always verify the specific method and parameter/header name required by the GurbaniNow API documentation as these can vary between services.

Security best practices

Securing your API keys is paramount to prevent unauthorized access to your GurbaniNow account and potential misuse of the API, which could lead to unexpected charges or service disruptions. Adopting a proactive security posture ensures the integrity of your applications and the reliability of your API integrations.

Key security measures:

  1. Keep API Keys Confidential: Treat your API keys as sensitive credentials, similar to passwords. Never hardcode them directly into client-side code (e.g., JavaScript running in a browser) or commit them to public version control systems like GitHub. If a client-side application needs to access the API, consider routing requests through a secure backend server that holds the API key.
  2. Use Environment Variables: For server-side applications, store API keys in environment variables rather than directly in your code. This practice prevents the key from being exposed if your codebase is compromised and allows for easier rotation of keys without code changes. Most programming languages and frameworks support reading environment variables.
  3. Restrict API Key Permissions: While GurbaniNow API keys generally grant access to data retrieval, if future updates introduce different scopes or permissions, always restrict keys to the minimum necessary privileges.
  4. Implement HTTPS: Always transmit API keys and make all API requests over HTTPS (HTTP Secure). HTTPS encrypts the communication between your application and the GurbaniNow servers, protecting the API key and other data from interception by malicious actors. Without HTTPS, your API key could be vulnerable to man-in-the-middle attacks.
  5. Monitor API Usage: Regularly monitor your API usage through your GurbaniNow account dashboard. Unusual spikes in requests could indicate that your API key has been compromised. Promptly investigate any suspicious activity.
  6. Rotate API Keys: Periodically rotate your API keys. This involves generating a new key and deactivating the old one. Regular rotation reduces the risk associated with a long-lived key being compromised over time.
  7. Implement Rate Limiting and Quotas: While GurbaniNow enforces its own rate limits, consider implementing client-side rate limiting in your application to prevent accidental overuse and to protect against denial-of-service attempts, even if an API key is legitimate.
  8. Secure Your Development Environment: Ensure that your development environment (local machine, CI/CD pipelines, cloud infrastructure) is secure. Use strong passwords, multi-factor authentication, and keep software updated to prevent unauthorized access to your source code and credentials.

By adhering to these security best practices, developers can significantly reduce the risk of API key compromise and ensure a secure, reliable integration with the GurbaniNow API.