FingerprintJS Pro Authentication: Methods & Best Practices (2026)

Authentication overview

FingerprintJS Pro employs a distinct authentication strategy tailored for device identification, differentiating between client-side and server-side interactions. The primary goal is to securely identify unique visitors and detect fraudulent activities without requiring user login credentials. Client-side operations, such as generating a visitor ID, typically do not use a secret key for authentication. Instead, a public API key is used to identify the customer making the request. This design allows for seamless integration into web and mobile applications for data collection. Conversely, server-side API calls, which involve retrieving or processing sensitive identification data, necessitate a secret API key for robust authentication and authorization.

This architecture is designed to balance ease of integration for client-side data collection with strict security for server-side data access. The separation ensures that while client applications can gather necessary device signals, access to aggregated or sensitive identification results is restricted to authenticated backend services. This approach aligns with industry standards for securing API interactions, particularly when dealing with potentially sensitive user-centric data like device fingerprints OAuth 2.0 Bearer Token usage.

Supported authentication methods

FingerprintJS Pro primarily relies on API keys for authenticating server-side requests. Client-side SDKs utilize a public API key for identification, but this key is not considered a secret authentication credential in the traditional sense, as it is exposed in the client application. The distinction between public and secret API keys is crucial for understanding the security model.

The client-side public API key is used to associate visitor data with your FingerprintJS Pro account. It's safe to embed this key directly in your client applications because it does not grant access to sensitive data or administrative functions. Instead, it merely identifies your application as the source of the device identification request. For server-to-server communication, such as retrieving detailed visitor information or configuring webhooks, the secret API key is paramount, offering a high level of security by authenticating the backend service making the request.

Getting your credentials

Accessing your FingerprintJS Pro API keys involves a straightforward process through the FingerprintJS Pro dashboard. Both public and secret API keys are generated and managed within your account settings.

1. Sign in to your FingerprintJS Pro dashboard: Navigate to the official FingerprintJS Pro homepage and access your account.
2. Access API Keys section: Typically found under "API Keys" or "Account Settings." Consult the FingerprintJS Pro API keys documentation for the exact location.
3. Identify your Public API Key: This key is displayed and can be copied for use in your client-side applications (JavaScript, Android, iOS, etc.).
4. Identify your Secret API Key: This key is also displayed but should be treated with extreme confidentiality. It is used for server-side integrations and should never be exposed in client-side code.
5. Key Rotation: The dashboard also provides functionality to rotate your API keys periodically or in case of a suspected compromise. Regular key rotation is a recommended security practice.

It is critical to securely store your secret API keys. For server-side applications, this often means using environment variables, dedicated secret management services, or secure configuration files, rather than hardcoding them directly into your codebase. For instance, cloud providers offer services like AWS Secrets Manager or Google Cloud Secret Manager for handling sensitive credentials AWS Secrets Manager overview.

Authenticated request example

Server-side authentication with FingerprintJS Pro typically involves including your secret API key in the X-API-Key header of your HTTP requests. The following example demonstrates a Node.js request to retrieve visitor history, illustrating the correct placement of the secret API key.

Node.js Example (Server-Side):

const fetch = require('node-fetch');

const visitorId = 'your_visitor_id'; // Replace with an actual visitor ID
const secretApiKey = process.env.FINGERPRINT_SECRET_API_KEY; // Stored securely as an environment variable

async function getVisitorHistory() {
  if (!secretApiKey) {
    console.error('FINGERPRINT_SECRET_API_KEY environment variable is not set.');
    return;
  }

  try {
    const response = await fetch(`https://api.fpjs.io/visitors/${visitorId}?limit=10`, {
      method: 'GET',
      headers: {
        'X-API-Key': secretApiKey,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Visitor History:', JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Error fetching visitor history:', error);
  }
}

getVisitorHistory();

In this example, process.env.FINGERPRINT_SECRET_API_KEY represents fetching the secret API key from an environment variable, which is a recommended practice for production environments. The X-API-Key header is then set with this value for the GET request to the FingerprintJS Pro API. This ensures that the request is properly authenticated and authorized to access the visitor's data.

Security best practices

Adhering to security best practices is essential when integrating FingerprintJS Pro to protect your application and user data. The following guidelines help mitigate common risks associated with API key management and usage:

• Never expose secret API keys client-side: Your secret API key must only be used on your backend servers. Exposing it in client-side code (e.g., JavaScript, mobile app bundles) allows unauthorized parties to impersonate your application and access sensitive data.
• Use environment variables or secret management services: Instead of hardcoding API keys, store them in environment variables or use dedicated secret management solutions like AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault. This prevents keys from being committed to version control systems and provides a centralized, secure way to manage credentials.
• Implement key rotation: Regularly rotate your secret API keys (e.g., every 90 days). This limits the window of exposure if a key is compromised. FingerprintJS Pro's dashboard provides tools for key rotation.
• Restrict API key permissions (if applicable): While FingerprintJS Pro's API keys typically have broad access within your account, always review the scope of permissions granted to any API key. In systems with more granular controls, adhere to the principle of least privilege.
• Monitor API key usage: Keep an eye on your API key usage patterns. Unusual spikes in requests or access from unexpected IP addresses could indicate a compromise. Set up alerts on your monitoring systems.
• Secure your backend infrastructure: Ensure that the servers making authenticated calls to FingerprintJS Pro are themselves secure. This includes regular patching, strong access controls, and network segmentation.
• Implement HTTPS: All communication with FingerprintJS Pro APIs should occur over HTTPS to encrypt data in transit, protecting against eavesdropping and man-in-the-middle attacks. This is standard for most modern API interactions, as detailed by the W3C's guidance on HTTPS.
• Validate and sanitize inputs: For any data sent to FingerprintJS Pro, ensure proper validation and sanitization to prevent injection attacks or malformed requests.
• Handle errors gracefully: Implement robust error handling for API calls. This can prevent information leakage and ensure your application remains stable even if API requests fail.

By following these best practices, developers can significantly enhance the security posture of their applications integrating with FingerprintJS Pro, protecting both their intellectual property and user privacy.