Private Keys

Private keys provide direct, full-access authentication for server-to-server integrations with the Enconvert API. They are the simplest way to authenticate and are suitable for any environment where the key can be kept confidential.

Header Format

Include your private key in the X-API-Key header with every request:

X-API-Key: sk_your_private_key

Private keys always begin with the sk_ prefix. You can generate and manage your keys from the Enconvert dashboard.

Usage

Private keys grant access to all API endpoints and features, including:

• All synchronous and asynchronous conversion endpoints
• Batch processing
• Job status polling and webhook notifications
• File uploads and URL-based conversions

No token exchange or session management is required. Simply include the key in each request.

Example: File Conversion

Convert a JSON file to XML using a private key:

cURL

curl -X POST https://api.enconvert.com/v1/convert/json-to-xml \
  -H "X-API-Key: sk_your_private_key" \
  -F "file=@data.json"

Response

{
  "presigned_url": "https://econverter.nyc3.cdn.digitaloceanspaces.com/...",
  "object_key": "live/files/12345/json-to-xml/data_20250202_120530123.xml",
  "filename": "data_20250202_120530123.xml",
  "file_size": 1024,
  "conversion_time_seconds": 0.45
}

• presigned_url -- A temporary, downloadable URL for retrieving the converted file.
• object_key -- The storage path of the converted file (e.g., live/files/12345/json-to-xml/...). This is not a URL.
• filename -- The generated filename for the converted file.
• file_size -- The size of the output file in bytes.
• conversion_time_seconds -- The time taken to complete the conversion.

Endpoint Restrictions

By default, a private key has access to all API endpoints. You can optionally restrict a key to specific endpoints using the allowed_endpoints setting in your dashboard.

When allowed_endpoints is configured, the key will only be able to call the listed endpoints. Requests to any other endpoint will be rejected with a 403 Forbidden error.

Example configuration:

{
  "allowed_endpoints": [
    "/v1/convert/url-to-pdf",
    "/v1/convert/json-to-xml",
    "/v1/convert/html-to-pdf"
  ]
}

This is useful when you want to issue a key with limited scope, for example, a key that can only perform PDF conversions.

Security

• Hashed storage: Private keys are stored on the server as SHA-256 hashes. The plaintext key is displayed only once at creation time. If you lose it, you must generate a new key.
• Key rotation: You can create multiple keys and revoke old ones at any time from the dashboard without downtime.
• Environment variables: Store your key in an environment variable (e.g., ENCONVERT_API_KEY) rather than hardcoding it in your source code.