API Documentation

Web Widgets

Web widgets allow you to embed Enconvert's file and URL conversion capabilities directly into any website. Visitors can perform conversions without leaving your page, and no API key is exposed in the frontend code.

Overview

Widgets are configured through the Enconvert dashboard and embedded as iframes. Each widget is tied to a single conversion endpoint and a list of allowed domains. Authentication is handled automatically using Cloudflare Turnstile challenges and short-lived JWT tokens.

How Widgets Work

  1. Create a widget from your Enconvert dashboard. Select the conversion endpoint (e.g., /v1/convert/url-to-pdf) and specify the domains where the widget will be embedded.
  2. Embed the iframe code into your website. No API key is needed in the embed code -- the widget handles authentication internally.
  3. Widget loads its configuration from GET /v1/widget/{widget_id}/config, which returns the endpoint, input type, allowed domains, and Turnstile site key.
  4. User completes a Turnstile challenge, the widget exchanges the challenge token for a JWT via POST /v1/widget/{widget_id}/token, and then uses that JWT to perform the conversion.

Widget Configuration Endpoint

Retrieves the configuration for a specific widget.

Request:

GET /v1/widget/{widget_id}/config

Response:

{
  "endpoint": "/v1/convert/url-to-pdf",
  "input_type": "url",
  "allowed_domains": ["https://example.com", "*.example.com"],
  "turnstile_site_key": "1x00000000000000000000AA"
}
  • endpoint -- The conversion endpoint this widget is configured to use.
  • input_type -- Indicates whether the widget accepts a URL input ("url") or a file upload ("file").
  • allowed_domains -- The list of domains authorized to embed and use this widget.
  • turnstile_site_key -- The Cloudflare Turnstile site key used for bot verification.

Widget Token Endpoint

Exchanges a Turnstile challenge token for a short-lived JWT that authorizes conversion requests.

Request:

POST /v1/widget/{widget_id}/token

Request body:

{
  "turnstile_token": "cloudflare-token"
}

Response:

{
  "token": "jwt-token",
  "token_type": "Bearer",
  "expires_in": 3600
}
  • token -- The JWT to include in the Authorization: Bearer <token> header for conversion requests.
  • token_type -- Always "Bearer".
  • expires_in -- Token validity in seconds (1 hour).

Widget Security

Widgets are designed with multiple layers of security to prevent abuse:

  • Domain whitelisting -- The widget only functions on domains explicitly listed in the widget configuration. Requests from unauthorized domains are rejected.
  • Turnstile verification -- Every token request requires a valid Cloudflare Turnstile challenge response, preventing automated abuse.
  • Origin validation -- The X-Parent-Origin header is checked against the allowed domains to verify the embedding page.
  • Endpoint restriction -- Each widget is locked to a single conversion endpoint. It cannot be used to access other API endpoints.
  • Token expiry -- JWT tokens issued to widgets expire after 1 hour and must be refreshed by completing a new Turnstile challenge.
← Parameters & Options Error Codes →