Scanii Authentication: API Key and HMAC Security (2026)

Authentication overview

Scanii employs a request-based authentication model to verify the identity of clients interacting with its API and to ensure the integrity of the data exchanged. This method is fundamental for any service that processes sensitive or critical data, such as real-time content scanning for malware detection. The core principle involves signing each API request with a unique secret key, which the Scanii service then uses to validate the request's origin and ensure it hasn't been tampered with in transit. This approach protects against unauthorized access and modification of scan requests or results. Scanii offers detailed documentation on its API authentication process, which is critical for developers integrating the service into their applications.

The authentication process is designed to be straightforward for developers while providing a high level of security. It relies on a combination of a public API Key ID and a private API Key Secret. The API Key ID identifies the client making the request, while the API Key Secret is used to create a cryptographic signature for each request. This signature, typically a Hash-based Message Authentication Code (HMAC), ensures that only parties possessing the correct secret can generate valid requests for a given API Key ID. For a broader understanding of API security principles, the Twilio API security guide provides additional context on protecting API endpoints.

Supported authentication methods

Scanii primarily supports two related authentication mechanisms for its API:

• API Key Authentication: For simpler, less security-critical operations or initial testing, requests can be authenticated using just an API Key ID and Secret sent as HTTP Basic Authentication credentials.
• HMAC Signature Authentication: For production environments and all critical operations, Scanii strongly recommends and often requires HMAC (Hash-based Message Authentication Code) signatures. This method provides robust message integrity and authenticity verification.

HMAC authentication involves generating a unique signature for each request using a cryptographic hash function (SHA-256) and your API Key Secret. This signature is then included in the request headers. Scanii's servers re-calculate the signature upon receiving the request and compare it with the one provided. A mismatch indicates either an unauthorized request or data tampering. This method aligns with common industry practices for securing RESTful APIs, as detailed in the AWS Signature Version 4 process, which also uses HMAC for request signing.

Authentication Method Comparison

Getting your credentials

To interact with the Scanii API, you first need to obtain an API Key ID and an API Key Secret. These credentials are generated and managed through the Scanii Management Console. The process typically involves:

1. Creating an Account: If you don't already have one, sign up for a Scanii account on their pricing page. A free developer plan is available for initial testing.
2. Accessing the Management Console: Log in to your Scanii account.
3. Generating API Keys: Navigate to the API Keys section within the console. Here, you can generate new API Key IDs and their corresponding Secrets. It is crucial to record your API Key Secret immediately upon generation, as it is typically shown only once for security reasons and cannot be retrieved later. If lost, you would need to generate a new key pair.
4. Managing Keys: The console also allows you to revoke existing API keys, which is important for security hygiene if a key is compromised or no longer needed.

Scanii's API reference documentation on authentication provides step-by-step instructions for credential generation and usage. It is recommended to create separate API keys for different applications or environments (e.g., development, staging, production) to limit the blast radius in case a key is compromised.

Authenticated request example

Implementing HMAC authentication involves several steps: constructing a canonical request, signing it with your API Key Secret, and adding the resulting signature to the HTTP headers. The following example demonstrates a Python implementation using the Scanii SDK, which abstracts much of this complexity. The SDKs provided by Scanii for languages like Ruby, Python, and Node.js are designed to simplify the authentication process by automatically handling the HMAC signature generation.

Python example using the Scanii SDK:

import scanii

# Replace with your actual API Key ID and Secret
api_key_id = "YOUR_SCANI_API_KEY_ID"
api_key_secret = "YOUR_SCANI_API_KEY_SECRET"

# Initialize the Scanii client
client = scanii.ScaniiClient(api_key_id, api_key_secret)

# Example: Submitting a file for scanning
# In a real application, 'example.txt' would be the path to the file you want to scan.
file_path = "./example.txt"

try:
    with open(file_path, 'rb') as f:
        # The SDK handles the HMAC signing automatically
        scan_result = client.process_file(f)
        print(f"Scan ID: {scan_result.id}")
        print(f"Scan Status: {scan_result.status}")
        if scan_result.findings:
            print("Findings:")
            for finding in scan_result.findings:
                print(f"  - {finding}")
        else:
            print("No findings detected.")
except scanii.ScaniiException as e:
    print(f"Scanii API Error: {e.message}")
except FileNotFoundError:
    print(f"Error: File not found at {file_path}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This Python code snippet illustrates how the Scanii SDK simplifies the interaction. When client.process_file(f) is called, the SDK internally constructs the necessary HTTP request, generates the HMAC signature using the provided api_key_id and api_key_secret, and adds the appropriate authentication headers before sending the request to the Scanii API. Developers using other languages can refer to the specific SDK documentation on the Scanii documentation portal for similar examples.

For direct API calls without an SDK, the manual process involves:

1. Canonical Request Creation: Normalize the HTTP method, path, query parameters, and body.
2. String-to-Sign: Combine the canonical request with a timestamp and other elements.
3. Signature Calculation: Compute an HMAC-SHA256 hash of the string-to-sign using your API Key Secret.
4. Authorization Header: Format the signature and API Key ID into an Authorization header.

This manual process is detailed in the Scanii API authentication guide and is crucial for understanding how the SDKs work under the hood or for implementing custom clients.

Security best practices

Adhering to security best practices is essential when integrating with any API, especially one handling security-critical functions like malware scanning. For Scanii authentication, consider the following:

• Protect API Keys: Treat your API Key Secret like a password. Never embed it directly in client-side code, commit it to version control systems (like Git), or expose it in public-facing applications. Store keys securely using environment variables, secret management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager), or secure configuration files.
• Use HMAC Authentication: Always prefer HMAC signature authentication over basic API key authentication for production environments. HMAC provides stronger security guarantees by verifying both the sender's identity and the integrity of the request payload, protecting against replay attacks and data tampering.
• Rotate Credentials Regularly: Implement a policy to regularly rotate your API keys (e.g., every 90 days). This practice limits the window of opportunity for an attacker if a key is compromised. Scanii's management console allows for easy key generation and revocation.
• Principle of Least Privilege: Create separate API keys for different applications or services, granting only the minimum necessary permissions to each key. While Scanii's current API key model grants broad access, isolating keys helps in identifying the source of compromise if one occurs.
• Monitor API Usage: Regularly review API access logs and usage patterns for any anomalies that might indicate unauthorized activity. Unexpected spikes in requests or requests from unusual geographical locations could signal a compromise.
• Secure Communication Channels: Always ensure all communication with the Scanii API occurs over HTTPS (TLS). This encrypts data in transit, protecting your API keys and the content being scanned from eavesdropping. All official Scanii endpoints exclusively use HTTPS.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could aid an attacker in identifying weaknesses. Generic error messages are preferred for public responses.
• SDK Usage: Utilize the official Scanii SDKs when available. These SDKs are designed to correctly implement the authentication mechanisms, reducing the risk of common implementation errors that could lead to vulnerabilities.

By following these guidelines, developers can significantly enhance the security posture of their applications integrating with the Scanii API, ensuring reliable and protected malware detection services.