Authentication overview

Api2Convert secures access to its file conversion and processing services primarily through API key authentication. This method ensures that only authorized applications and users can interact with the API, protecting both user data and the integrity of the service. API keys are unique identifiers assigned to a user or application, acting as both a unique identifier and a secret token for authentication. When making requests to the Api2Convert API, this key must be included to prove the identity and authorization of the caller, allowing the system to track usage and enforce any rate limits or plan restrictions associated with the account.

The system is designed to handle various conversion tasks, including document, image, and archive conversions, as well as OCR capabilities, all requiring proper authentication to initiate a job. Api2Convert's documentation provides specific guidelines on how to integrate these keys across different programming languages, supported by several official SDKs including PHP, Node.js, Python, .NET, Go, Ruby, and Java SDKs. Adherence to these authentication protocols is crucial for maintaining the security and operational efficiency of applications built on the Api2Convert platform.

Supported authentication methods

Api2Convert primarily supports API Key authentication. This method is common for RESTful APIs due to its simplicity and ease of implementation for server-to-server communication and client-side applications where the key can be securely managed. The API key serves as a unique identifier and a secret token, which must be transmitted with each API request to verify the sender's identity and permissions.

API Key

An API key is a token that a client provides when making API calls. It identifies the calling project and provides authorization. Api2Convert expects the API key to be sent either as a query parameter or in a custom HTTP header. When transmitted over HTTPS, API keys offer a reasonable level of security for identifying the client making the request. However, it is essential to manage API keys securely to prevent unauthorized access, as their exposure could lead to misuse of the API by malicious actors.

Comparison of Authentication Methods

Method When to Use Security Level
API Key Server-to-server communication, client-side applications with secure key management, simple integrations Moderate (requires secure storage and transmission over HTTPS)

While API keys are effective for many use cases, more robust authentication mechanisms like OAuth 2.0 might be considered for applications requiring delegated authorization or user-specific permissions without exposing user credentials directly. However, Api2Convert's current authentication model focuses on the streamlined use of API keys for all supported operations.

Getting your credentials

To begin using the Api2Convert API, you must first obtain an API key. This key is your credential for authenticating all requests to the service.

Steps to obtain your Api2Convert API key:

  1. Create an Account: Navigate to the Api2Convert homepage and sign up for a new account if you do not already have one. A free tier is available, offering 50 conversions per month, which is suitable for initial testing and development.
  2. Access the Dashboard: Once registered and logged in, you will be directed to your personal dashboard.
  3. Locate API Key Section: Within the dashboard, look for a section typically labeled "API Keys", "Settings", or "Developer Settings". The exact location may vary, but it is usually prominently displayed.
  4. Generate/Retrieve Key: Your API key will be displayed in this section. If it's your first time, you may need to click a "Generate API Key" button. Copy this key immediately and store it securely. Treat your API key like a password; do not share it publicly or commit it to version control systems.
  5. Review Documentation: For any specific instructions on key management or rotation, consult the official Api2Convert documentation.

It is crucial to keep your API key confidential. Compromised keys can lead to unauthorized access to your account's conversion limits and potentially expose your data to unauthorized third parties. If you suspect your API key has been compromised, you should revoke it from your dashboard and generate a new one immediately.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests. Api2Convert supports sending the API key either as a query parameter or within an HTTP header. The method depends on the specific endpoint and SDK usage, but generally, inclusion in the header is preferred for security reasons.

Example using Node.js (with axios)

This example demonstrates how to make an authenticated request using Node.js, sending the API key as a custom HTTP header named X-Api-Key. This approach is recommended for server-side applications.


const axios = require('axios');

const API_KEY = 'YOUR_API_KEY'; // Replace with your actual API key
const FILE_URL = 'https://example.com/document.docx'; // URL of the file to convert
const TARGET_FORMAT = 'pdf'; // Target format for conversion

async function convertFile() {
    try {
        const response = await axios.post(
            'https://api.api2convert.com/v1/convert',
            {
                file: FILE_URL,
                targetFormat: TARGET_FORMAT
            },
            {
                headers: {
                    'Content-Type': 'application/json',
                    'X-Api-Key': API_KEY // API Key in custom header
                }
            }
        );
        console.log('Conversion initiated successfully. Job ID:', response.data.jobId);
        console.log('Download URL:', response.data.downloadUrl);
    } catch (error) {
        console.error('Error during conversion:', error.response ? error.response.data : error.message);
    }
}

convertFile();

Example using Python (with requests)

This Python example also uses a custom HTTP header for the API key.


import requests

API_KEY = 'YOUR_API_KEY' # Replace with your actual API key
FILE_URL = 'https://example.com/image.jpg'
TARGET_FORMAT = 'png'

def convert_file():
    headers = {
        'Content-Type': 'application/json',
        'X-Api-Key': API_KEY  # API Key in custom header
    }
    payload = {
        'file': FILE_URL,
        'targetFormat': TARGET_FORMAT
    }
    response = requests.post('https://api.api2convert.com/v1/convert', json=payload, headers=headers)

    if response.status_code == 200:
        data = response.json()
        print(f"Conversion initiated successfully. Job ID: {data.get('jobId')}")
        print(f"Download URL: {data.get('downloadUrl')}")
    else:
        print(f"Error during conversion: {response.status_code} - {response.text}")

if __name__ == '__main__':
    convert_file()

For more detailed examples across other languages and specific API endpoints, refer to the Api2Convert documentation.

Security best practices

Securing your API keys and authentication processes is paramount to protect your applications and data when integrating with Api2Convert. Following these best practices helps mitigate risks associated with unauthorized access and misuse.

  • Keep API Keys Confidential: Treat your API key like a password. Never embed it directly in client-side code (e.g., JavaScript in a browser), public repositories (like GitHub), or client-facing applications where it could be easily extracted. Instead, use environment variables, secret management services, or a backend proxy to inject the key into requests.
  • Use HTTPS/TLS for All Requests: Api2Convert API endpoints should always be accessed via HTTPS. This encrypts the communication channel between your application and the API, preventing eavesdropping and tampering with your API key and data in transit. The use of Transport Layer Security (TLS) is a fundamental security requirement for any web-based API interaction.
  • Implement Server-Side Authentication: For web applications, all API calls to Api2Convert should ideally originate from your backend server. Your server can securely store the API key and relay requests to Api2Convert on behalf of your users, rather than exposing the key to client-side code.
  • Rotate API Keys Regularly: Periodically rotate your API keys. This practice minimizes the window of opportunity for a compromised key to be exploited. Check your Api2Convert dashboard for options to revoke old keys and generate new ones.
  • Restrict API Key Permissions (if applicable): While Api2Convert's API keys might have broad permissions, if there are options to scope keys to specific functionalities or IP addresses, utilize them. This limits the damage if a key is compromised. Always follow the principle of least privilege.
  • Monitor API Usage: Regularly monitor your API usage logs and billing. Unusual spikes in activity or unexpected conversion requests could indicate a compromised API key. Api2Convert's dashboard should provide tools for tracking usage.
  • Error Handling and Logging: Implement robust error handling for authentication failures. Avoid logging API keys or other sensitive credentials in application logs. If logging is necessary for debugging, ensure logs are secured and purged regularly.
  • Secure Development Lifecycle: Integrate API key security into your development lifecycle, from design to deployment. Conduct regular security audits and penetration testing on applications that use API keys.

By adhering to these security best practices, developers can significantly enhance the protection of their applications and the data processed through the Api2Convert service, ensuring a secure and reliable integration.