CloudConvert Authentication: API Key & OAuth 2.0 (2026)

Authentication overview

CloudConvert provides an API for programmatic file format conversions, integrating these capabilities into various applications and workflows. Secure access to this API is managed through two primary authentication methods: API keys and OAuth 2.0. The choice between these methods depends on the application's architecture and security requirements.

API keys offer a straightforward approach for server-to-server communication where a single application or service accesses the API on its own behalf. This method is suitable for backend processes, scripts, or command-line tools that do not require user interaction for authorization.

OAuth 2.0, in contrast, provides a secure framework for delegated authorization, allowing third-party applications to access a user's CloudConvert account without exposing their credentials. This is particularly relevant for web and mobile applications that need to perform conversions on behalf of their users. The OAuth 2.0 specification is an industry-standard protocol for authorization and is widely adopted across many APIs, including CloudConvert's, to ensure secure user consent and token-based access.

All interactions with the CloudConvert API, regardless of the authentication method, must occur over HTTPS to ensure that data in transit, including authentication credentials and API requests, is encrypted and protected from interception. CloudConvert's API adheres to RESTful principles, making it predictable and easy to integrate with standard HTTP clients.

Supported authentication methods

CloudConvert supports API Key authentication and OAuth 2.0 for accessing its API. Each method is designed for specific use cases, offering different levels of security and integration complexity.

API key authentication

API keys are single, static tokens used to authenticate requests. When using API keys:

• Mechanism: The API key is included in the request headers, typically in the Authorization header using the Bearer scheme, or as a query parameter.
• Suitability: Ideal for server-side applications, scripts, and internal tools where the key can be securely stored and managed. It grants direct access to the account's API capabilities.
• Security Considerations: API keys provide direct access to your account. Their compromise can lead to unauthorized usage. Best practices recommend restricting API key permissions and ensuring secure storage.

OAuth 2.0 authentication

OAuth 2.0 enables third-party applications to obtain limited access to a user's CloudConvert account without requiring their username and password. This is achieved through access tokens.

• Mechanism: CloudConvert primarily supports the Authorization Code Grant flow. This involves redirecting the user to CloudConvert for authorization, receiving an authorization code, and then exchanging this code for an access token and refresh token.
• Suitability: Best for public client applications like web applications where users grant explicit permission for an application to act on their behalf. This delegates authentication responsibility to CloudConvert.
• Security Considerations: Access tokens are short-lived, reducing the impact of compromise. Refresh tokens allow for obtaining new access tokens without re-authenticating the user. Client secrets must be kept confidential on the server-side. The OAuth 2.0 framework is detailed in RFC 6749 by the IETF.

The following table summarizes the key characteristics of each authentication method:

Getting your credentials

To interact with the CloudConvert API, you will need to obtain appropriate credentials from your CloudConvert account dashboard. The process varies slightly depending on whether you require an API key or OAuth 2.0 client credentials.

For API keys

1. Log in: Access your CloudConvert account dashboard at cloudconvert.com.
2. Navigate to API settings: Locate the "API" or "Developers" section in your account settings.
3. Generate API key: Within this section, typically under "API Keys", you will find an option to generate a new API key. CloudConvert allows you to create multiple API keys for different applications or environments, enhancing security through segmentation.
4. Copy and store: Once generated, the API key will be displayed. Copy it immediately and store it securely. CloudConvert generally shows API keys only once upon generation; you will not be able to retrieve it again later.

For detailed instructions on managing API keys, refer to the CloudConvert API documentation on authentication.

For OAuth 2.0 client credentials

If you are building a web application that interacts with CloudConvert on behalf of users, you will need OAuth 2.0 client credentials (Client ID and Client Secret).

1. Register your application: In your CloudConvert dashboard's API or Developer section, look for an option to "Register Application" or "OAuth Clients".
2. Provide application details: You will need to provide information such as your application's name, description, and crucially, one or more valid Redirect URIs (callback URLs). These are the URLs to which CloudConvert will redirect the user after they authorize your application.
3. Generate credentials: Upon successful registration, CloudConvert will provide you with a Client ID and Client Secret. The Client Secret, like an API key, should be treated as highly confidential and stored securely.
4. Configure scopes: Define the necessary API scopes (permissions) that your application requires. Scopes limit the access an application has to a user's account, adhering to the principle of least privilege.

Further guidance on setting up OAuth 2.0 applications and managing scopes is available in the CloudConvert OAuth 2.0 documentation.

Authenticated request example

Here's an example of an authenticated request using an API key to submit a file conversion job to CloudConvert. This example uses curl, but similar logic applies to the CloudConvert SDKs for PHP, Node.js, or Python.

Using an API key (Bearer Token)

When using an API key, it is typically passed in the Authorization header with the Bearer scheme.

curl -X POST \
  https://api.cloudconvert.com/v2/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "my-job-tag",
    "tasks": {
      "import-my-file": {
        "operation": "import/url",
        "url": "https://example.com/document.docx"
      },
      "convert-my-file": {
        "operation": "convert",
        "input": "import-my-file",
        "output_format": "pdf",
        "filename": "document.pdf"
      },
      "export-my-file": {
        "operation": "export/url",
        "input": "convert-my-file"
      }
    }
  }'

In this example:

• YOUR_API_KEY should be replaced with your actual CloudConvert API key.
• The request creates a "job" that imports a DOCX file from a URL, converts it to PDF, and then exports the resulting PDF to a CloudConvert-hosted URL.
• The Authorization: Bearer header is the standard way to pass the API key as a JSON Web Token (JWT) or a plain bearer token, ensuring the request is authenticated.

Using OAuth 2.0 (Access Token)

After completing the OAuth 2.0 flow and obtaining an access token, you would use it in the same manner as an API key in the Authorization header:

curl -X POST \
  https://api.cloudconvert.com/v2/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "user-job-tag",
    "tasks": {
      "import-user-file": {
        "operation": "import/url",
        "url": "https://usersite.com/user_doc.pptx"
      },
      "convert-user-file": {
        "operation": "convert",
        "input": "import-user-file",
        "output_format": "pdf",
        "filename": "user_doc.pdf"
      },
      "export-user-file": {
        "operation": "export/url",
        "input": "convert-user-file"
      }
    }
  }'

Here, YOUR_ACCESS_TOKEN represents the token obtained via the OAuth 2.0 flow. This allows the application to perform actions on behalf of the user who granted the token, adhering to the permissions defined by the token's scopes.

Security best practices

Implementing strong security measures for authentication is crucial to protect your CloudConvert account and user data. Adhere to these best practices:

API key management

• Keep keys confidential: Never embed API keys directly in client-side code (e.g., JavaScript in a web browser, mobile app binaries) or publicly accessible repositories. They should be stored and used only on secure backend servers.
• Use environment variables: Store API keys as environment variables in your server environment rather than hardcoding them into your application's source code. This prevents them from being exposed in version control systems.
• Rotate keys regularly: Periodically generate new API keys and revoke old ones. This minimizes the window of opportunity for a compromised key to be exploited.
• Implement IP whitelisting: If CloudConvert supports it, restrict API key usage to a specific list of trusted IP addresses. This adds an extra layer of security, ensuring that even if a key is stolen, it can only be used from authorized locations.
• Monitor usage: Regularly review your CloudConvert API usage logs for any unusual activity that might indicate unauthorized access.

OAuth 2.0 best practices

• Secure client secret: For confidential clients, the client secret must be kept as secure as an API key. It should never be exposed in client-side code.
• Validate redirect URIs: Ensure that your registered redirect URIs are strictly controlled and point only to legitimate endpoints. Only use HTTPS for redirect URIs.
• Use state parameter: Implement the state parameter in your OAuth authorization requests to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter is a randomly generated value that your application passes to CloudConvert and then verifies when the user is redirected back.
• Handle tokens securely: Store refresh tokens encrypted and never expose them. Access tokens should also be handled securely and invalidated if compromised.
• Request minimal scopes: Follow the principle of least privilege by requesting only the necessary scopes for your application's functionality. This limits the potential impact if your access token is compromised.
• Token expiration and refresh: Design your application to handle access token expiration gracefully using refresh tokens to obtain new access tokens without requiring user re-authentication.

General security considerations

• Always use HTTPS: Ensure all API communication uses HTTPS/TLS to encrypt data in transit, protecting credentials and data from eavesdropping. CloudConvert enforces this for all API endpoints.
• Error handling: Implement robust error handling that does not reveal sensitive information about your authentication mechanism or internal system details.
• Code reviews: Conduct regular code reviews to identify and rectify potential security vulnerabilities related to authentication and credential handling.
• Stay updated: Keep your CloudConvert SDKs and dependencies updated to benefit from the latest security patches and improvements.

By adhering to these security best practices, developers can significantly reduce the risk of unauthorized access and protect the integrity of their CloudConvert integrations.