Authentication overview

Authentication for Cloudmersive APIs establishes and verifies the identity of the client making a request, ensuring that only authorized applications and users can access the available services. Cloudmersive implements a straightforward authentication model, primarily utilizing API keys to manage access to its various endpoints for tasks such as virus scanning files, document format conversion, and image content analysis. This method simplifies integration while providing a mechanism for usage tracking and security.

When an API key is included in an API request, the Cloudmersive system validates the key against its records. A valid key grants access to the requested API function, provided the account associated with the key has the necessary permissions and remaining call quota. Invalid or missing API keys result in authentication failures, preventing the request from proceeding and protecting the API resources. This approach aligns with common practices for API key authentication across various platforms, offering a balance between ease of use and security.

Supported authentication methods

Cloudmersive primarily supports authentication through API keys. This method involves generating a unique string of characters that acts as a secret token, identifying the client application when making API calls. The API key is typically passed in the request header or as a query parameter.

API Key

The Cloudmersive API key is a unique identifier assigned to each developer account. It serves as a credential used to authenticate API requests. When developers sign up for a Cloudmersive account, an API key is automatically generated and can be managed through the Cloudmersive developer portal. This key must be included with every API request to authorize access to the Cloudmersive services.

How API Keys Function

API keys are generally sent in the Apikey HTTP header for most Cloudmersive API calls. For certain operations, like uploading files, the API key might also be passed as a query parameter in the URL. Cloudmersive's SDKs abstract this detail, handling the correct placement of the API key within requests based on the specific API endpoint being called.

The following table summarizes the primary authentication method:

Method When to Use Security Level
API Key All Cloudmersive API calls for access control and usage tracking. Moderate. Requires secure handling and storage of the key.

Getting your credentials

To begin using Cloudmersive APIs, you need to obtain an API key. This process is initiated by creating an account on the Cloudmersive developer portal.

  1. Sign Up or Log In: Navigate to the Cloudmersive developer portal and either create a new account or log in to an existing one. Account creation typically requires an email address and password.
  2. Access API Key: Upon successful login, your API key is usually displayed on your account dashboard or a dedicated 'API Key' section. Cloudmersive automatically generates a unique API key for each new account.
  3. Copy and Store Securely: Copy your API key and store it in a secure location. Avoid hardcoding API keys directly into your application code, especially in client-side applications. Use environment variables or a secrets management service instead.
  4. Free Tier Usage: Cloudmersive offers a free API key that allows up to 800 calls per month, enabling developers to test and integrate without immediate cost.

Authenticated request example

This section demonstrates how to include your Cloudmersive API key in a request using various programming languages. The examples assume you have already obtained your API key from the Cloudmersive developer portal.

C# Example

Using the Cloudmersive C# SDK, set the API key in the configuration:


using Cloudmersive.APIClient.NET.DocumentAndDataConvert.Api;
using Cloudmersive.APIClient.NET.DocumentAndDataConvert.Client;

// Configure API key authorization:
Configuration.Default.ApiKey.Add("Apikey", "YOUR_CLOUDMERSIVE_API_KEY");

var apiInstance = new ConvertDocumentApi();
try
{
    // Example: Convert DOCX to PDF
    // var inputFile = new System.IO.FileStream("C:\\path\\to\\input.docx", System.IO.FileMode.Open);
    // var result = apiInstance.ConvertDocumentAutodetectToPdf(inputFile);
    // Console.WriteLine(result.ToJson());
}
catch (Exception e)
{
    Console.WriteLine("Exception when calling ConvertDocumentApi: " + e.Message);
}

Java Example

For Java applications with the Cloudmersive SDK:


import com.cloudmersive.client.invoker.ApiClient;
import com.cloudmersive.client.invoker.ApiException;
import com.cloudmersive.client.invoker.Configuration;
import com.cloudmersive.client.invoker.auth.*;
import com.cloudmersive.client.ConvertDocumentApi;

public class ConvertDocumentExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        ApiKeyAuth Apikey = (ApiKeyAuth) defaultClient.getAuthentication("Apikey");
        Apikey.setApiKey("YOUR_CLOUDMERSIVE_API_KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token"
        //Apikey.setApiKeyPrefix("Token");

        ConvertDocumentApi apiInstance = new ConvertDocumentApi();
        try {
            // Example: Convert DOCX to PDF
            // File inputFile = new File("path/to/input.docx"); // File | Input file to perform the operation on.
            // byte[] result = apiInstance.convertDocumentAutodetectToPdf(inputFile);
            // System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling ConvertDocumentApi#convertDocumentAutodetectToPdf");
            e.printStackTrace();
        }
    }
}

Python Example

Integrating with Python using the Cloudmersive SDK:


import time
import cloudmersive_convert_api_client
from cloudmersive_convert_api_client.rest import ApiException
from pprint import pprint

# Configure API key authorization:
configuration = cloudmersive_convert_api_client.Configuration(host="https://api.cloudmersive.com")
configuration.api_key['Apikey'] = 'YOUR_CLOUDMERSIVE_API_KEY'

# create an instance of the API class
api_instance = cloudmersive_convert_api_client.ConvertDocumentApi(cloudmersive_convert_api_client.ApiClient(configuration))
# inputFile = '/path/to/file' # file | Input file to perform the operation on.

try:
    # Convert DOCX to PDF
    # api_response = api_instance.convert_document_autodetect_to_pdf(inputFile)
    # pprint(api_response)
except ApiException as e:
    print("Exception when calling ConvertDocumentApi->convert_document_autodetect_to_pdf: %s\n" % e)

Node.js Example

For Node.js applications with the Cloudmersive SDK:


var CloudmersiveConvertApiClient = require('cloudmersive-convert-api-client');
var defaultClient = CloudmersiveConvertApiClient.ApiClient.instance;

// Configure API key authorization:
var Apikey = defaultClient.authentications['Apikey'];
Apikey.apiKey = 'YOUR_CLOUDMERSIVE_API_KEY';

var api = new CloudmersiveConvertApiClient.ConvertDocumentApi();

// var inputFile = Buffer.from(fs.readFileSync("C:\\temp\\input.docx").buffer); // File | Input file to perform the operation on.

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    // console.log('API called successfully. Returned data: ' + data);
  }
};
// api.convertDocumentAutodetectToPdf(inputFile, callback);

Security best practices

Securing your Cloudmersive API keys and integrations is crucial to prevent unauthorized access and potential misuse of your account. Adhering to these best practices can mitigate common security risks:

  • Protect API Keys: Treat your API key as you would any sensitive credential, such as a username and password. Avoid embedding keys directly into client-side code, public repositories, or any location accessible without proper authorization.
  • Use Environment Variables: For server-side applications, store API keys in environment variables rather than hardcoding them into source code. This practice keeps keys separate from the codebase and prevents them from being exposed in version control systems.
  • Implement a Secrets Management Solution: For complex deployments or enterprise environments, consider using a dedicated secrets management service (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager) to securely store and retrieve API keys, enhancing security and auditability. These services provide centralized management, encryption, and access control for sensitive data.AWS Secrets Manager overview.
  • Restrict API Key Scopes (If Available): While Cloudmersive's API keys currently grant access across all enabled services for an account, always confirm if a platform offers scope or permission restrictions for keys. If such features become available, configure your keys to have the minimum necessary permissions to perform their intended function.
  • Rotate API Keys Regularly: Periodically generate new API keys and replace old ones. This practice minimizes the window of opportunity for a compromised key to be exploited. Establish a rotation schedule appropriate for your security policies.
  • Monitor API Usage: Regularly review your Cloudmersive API usage statistics in the developer portal. Unusual spikes or activity patterns could indicate a compromised key or unauthorized access.
  • Secure Your Development Environment: Ensure that your development machines and build pipelines are secure. Malicious software or improper access controls in these environments can expose API keys before deployment.
  • Use HTTPS: Always transmit API keys and make API requests over HTTPS (TLS/SSL) to encrypt data in transit, protecting against eavesdropping and man-in-the-middle attacks. Cloudmersive APIs enforce HTTPS.
  • Implement Rate Limiting and Circuit Breakers: While not directly an authentication security measure, implementing client-side rate limiting and circuit breakers can prevent excessive API calls in case a key is compromised and used to launch a denial-of-service attack against your quota.