API Documentation

Authentication

The Enconvert API supports two authentication methods, each designed for different use cases. Choose the method that matches your integration scenario.

Overview

Method Key Prefix Use Case Auth Header
Private Keys sk_ Server-to-server X-API-Key: sk_...
Public Keys + JWT pk_ Client-side (browsers) Authorization: Bearer <token>

Private Keys

Private keys are intended for server-side applications where your API key can be kept secret. They provide full access to all API endpoints and features.

  • Header: X-API-Key: sk_your_private_key
  • Access: Full access to all endpoints, including sync and async operations, batch processing, and all conversion types.
  • Security: Keys are stored as SHA-256 hashes on the server. The plaintext key is shown only once at creation time.
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
Security Warning: Never use private keys (sk_) in client-side code such as browsers or mobile apps. The API detects the Origin header sent by browsers and will reject requests made with private keys from browser environments. Use public keys with JWT for client-side integrations instead.

For full details, see Private Keys.

Public Keys + JWT

Public keys are designed for client-side applications running in browsers. Because the key is visible to end users, it cannot grant direct API access. Instead, the public key is exchanged for a short-lived JWT token, which is then used to authenticate subsequent requests.

  • Step 1: Exchange your public key (pk_) for a JWT token via POST /v1/auth/token.
  • Step 2: Use the JWT token in the Authorization: Bearer <token> header for API requests.
  • Step 3: Refresh the token automatically before it expires using POST /v1/auth/refresh.
  • Domain whitelisting: Public keys are restricted to requests originating from whitelisted domains, configured in your dashboard.
// Step 1: Get a JWT token
const response = await fetch("https://api.enconvert.com/v1/auth/token", {
  method: "POST",
  headers: {
    "X-API-Key": "pk_your_public_key",
    "X-Parent-Origin": window.location.origin,
  },
  credentials: "include",
});
const { token } = await response.json();

// Step 2: Use the token
const result = await fetch("https://api.enconvert.com/v1/convert/url-to-pdf", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

For full details, see Public Keys + JWT.

Choosing the Right Method

  • Building a backend service, script, or internal tool? Use a private key (sk_). It is simpler and gives full access.
  • Building a browser-based app or widget? Use a public key (pk_) with JWT. It keeps your credentials safe and restricts access to whitelisted domains.
← Quick Start Private Keys →