Filestack Authentication: API Key & Signature Security (2026)

Authentication overview

Filestack employs authentication to ensure that only authorized applications and users can interact with its API for file uploads, transformations, and delivery operations. This system protects your content and prevents unauthorized access to your Filestack account and associated storage. The core of Filestack's authentication mechanism involves the use of an API Key, which identifies your application. For enhanced security and fine-grained control over file operations, a combination of a security policy and a digital signature can be implemented. This approach allows developers to define specific permissions, such as allowed operations, maximum file sizes, and expiration times for access tokens, ensuring that requests align with predefined security rules before execution. Understanding both the basic API Key usage and the more advanced policy-signature model is crucial for building secure and robust applications with Filestack.

The choice of authentication method depends on the security requirements of your application. For simple client-side uploads, an API Key might suffice, but for server-side operations or scenarios requiring strict access control, implementing policies and signatures is recommended. This layered security approach is a common practice in modern web services, providing flexibility without compromising data integrity. For instance, OAuth 2.0 is a widely adopted authorization framework that also separates client identification from specific resource access permissions, similar in principle to how Filestack's policies define granular access OAuth 2.0 specification overview.

Supported authentication methods

Filestack primarily supports two authentication methods, which can be used independently or in combination:

1. API Key authentication: This is the simplest method, where an API Key is included with every request to identify your application. It grants general access to your Filestack account's resources.
2. Policy and Signature authentication: This method provides a higher level of security by combining an API Key with a cryptographically signed policy. The policy defines specific permissions and constraints for an operation (e.g., allowed IP addresses, file types, maximum size, expiration date), and the signature verifies that the policy has not been tampered with.

The following table outlines when to use each method and its security implications:

For operations that involve sensitive data or require strict access control, Filestack strongly recommends implementing the Policy and Signature method. This method prevents malicious users from manipulating requests or accessing unauthorized resources by enforcing server-side validation of the policy's terms. For example, a policy can specify that a file upload is only valid for 60 minutes and only from a specific IP address, adding a crucial layer of security Filestack security overview.

Getting your credentials

To begin using Filestack, you must obtain an API Key. If you plan to implement Policy and Signature authentication, you will also need a secret key to generate the signature. Both of these credentials can be managed through the Filestack Developer Portal:

1. Sign Up/Log In: Navigate to the Filestack documentation and either sign up for a new account or log in to an existing one.
2. Access Your Dashboard: Once logged in, go to your Developer Portal dashboard.
3. Locate API Key: Your API Key is typically displayed prominently on the dashboard. This key is used in all Filestack API requests to identify your account.
4. Generate Secret Key (for Policy & Signature): To enable Policy and Signature authentication, you will need to generate a secret key. This option is usually found in the 'Security' or 'API Keys' section of your dashboard. The secret key is used in conjunction with your API Key to create the digital signature for your policies. Keep this secret key confidential, as it is critical for generating valid signatures and should never be exposed in client-side code.

Filestack provides tools within the dashboard to regenerate your API Key or secret key if they are compromised or if you follow a regular key rotation schedule. Regular key rotation is a common security practice to minimize the impact of a potential key compromise, as recommended by cybersecurity guidelines for API security Google Cloud API security best practices.

Authenticated request example

This example demonstrates how to perform a simple authenticated upload using the Filestack JavaScript SDK with an API Key. For operations requiring higher security, you would additionally generate a policy and signature on your backend and pass them to the SDK.

<!DOCTYPE html>
<html>
<head>
  <title>Filestack Upload Example</title>
  <script src="https://static.filestackapi.com/filestack-js/3.x.x/filestack.min.js"></script>
</head>
<body>
  <input type="file" id="fileupload">
  <script>
    const client = filestack.init('YOUR_API_KEY'); // Replace with your actual API Key

    document.getElementById('fileupload').addEventListener('change', (event) => {
      const file = event.target.files[0];
      if (file) {
        client.upload(file)
          .then(res => {
            console.log('Upload successful:', res);
            alert('File uploaded successfully! URL: ' + res.url);
          })
          .catch(err => {
            console.error('Upload error:', err);
            alert('Upload failed: ' + err.message);
          });
      }
    });
  </script>
</body>
</html>

To implement Policy and Signature authentication, you would modify the filestack.init call to include your policy and signature, which should be generated on your server-side using your secret key. The policy is a JSON object defining the permissions, base64 encoded, and then signed using HMAC-SHA256 with your secret key. The resulting signature is then URL-safe base64 encoded. Refer to the Filestack security documentation for detailed steps on generating policies and signatures.

// Example of initializing with Policy and Signature (simplified - policy/signature should come from your backend)
// For actual implementation, policy and signature should be generated on your server.
const policy = 'YOUR_BASE64_ENCODED_POLICY'; // e.g., eyJleHBpcnkiOiAxNDY1ODU2Nzg1LCAiY2FsbHMiOiBbInJlYWQiLCAidXBsb2FkIl0sICJtYXhTaXplIjogMTA0ODU3NjB9
const signature = 'YOUR_BASE64_ENCODED_SIGNATURE'; // e.g., Y2NkM2MwYjFkZGIzYjNjZTYxMzI2MmY0NzQ2Njg5YzA3YjI0ZDUxM2Q3YmRjMzQ4Y2E4MzMwN2Y1M2NlMTQx

const clientWithSecurity = filestack.init('YOUR_API_KEY', { policy: policy, signature: signature });

// Then use clientWithSecurity for operations that require these permissions

This approach ensures that even if your API Key is exposed on the client side, operations are still constrained by the server-generated policy and validated by the signature, preventing unauthorized or malicious actions.

Security best practices

Implementing robust security measures is crucial when integrating any API. For Filestack, consider the following best practices:

• Protect your API Key: Never hardcode your API Key directly into client-side code, especially if not paired with a policy and signature. Use environment variables or a configuration management system to inject keys securely, particularly in server-side applications.
• Use Policy and Signature authentication for all sensitive operations: For production environments and any operation involving sensitive data (uploads, private transformations, secure delivery), always generate policies and signatures on your backend. This prevents client-side tampering with permissions and ensures requests adhere to predefined rules.
• Keep your Secret Key confidential: Your secret key is used to generate signatures and should be treated with the utmost secrecy. Never expose it in client-side code or commit it to version control systems. Store it in secure environment variables, a secrets manager, or a hardware security module (HSM).
• Implement granular policies: When creating policies, define the narrowest possible permissions. For example, specify exact calls allowed, set expiration times, limit file sizes, and restrict IP addresses to minimize the attack surface.
• Regularly rotate API Keys and Secret Keys: Periodically regenerate your API Keys and secret keys through the Filestack Developer Portal. This practice reduces the risk associated with a compromised key over time.
• Monitor API usage: Regularly review your Filestack dashboard and logs for unusual activity or excessive API calls that could indicate unauthorized use.
• Validate inputs: Always validate all user inputs on your server before generating policies or making API calls to prevent injection attacks or other vulnerabilities.
• Secure your backend: Ensure your server-side application generating policies and signatures is secure, following general web security best practices such as using HTTPS, strong password policies, and regular security audits. Services like Cloudflare WAF can help protect your backend from common web vulnerabilities.

By adhering to these best practices, you can significantly enhance the security posture of your Filestack integration and protect your application and user data.