Embed a File Converter Widget on Your Website#

Enconvert web widgets let you embed URL and file conversion directly into any website with a single script tag — visitors convert URLs to PDFs, capture screenshots, or convert uploaded files without leaving your page. Each widget authenticates through Cloudflare Turnstile challenges and short-lived JWTs issued by POST /v1/widget/{widget_id}/token, so no API key is ever exposed in your frontend code. Every conversion runs synchronously and returns a JSON response with a presigned download URL.

Overview#

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

Supported conversion endpoints:

Any Enconvert conversion endpoint can be used with widgets, including:

• URL-based: url-to-pdf, url-to-screenshot
• File-based: All data format, document to PDF, and image conversion endpoints

How Widgets Work#

Setup#

1. Go to your Enconvert Dashboard > Widgets and click Create Widget.
2. Select the conversion endpoint (e.g., /v1/convert/url-to-pdf) and specify the domains where the widget will be embedded. Wildcard subdomains are supported (e.g., *.example.com).
3. An internal public API key is automatically created for the widget, restricted to the selected endpoint and allowed domains. This key is never exposed.

Embedding#

Add the embed script to your website:

<script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>

The script creates a sandboxed iframe that loads the Enconvert widget. No API key appears in the embed code.

Runtime Flow#

1. Widget loads in the iframe and fetches its configuration from GET /v1/widget/{widget_id}/config.
2. Domain validation -- the widget verifies the parent page's origin matches the allowed domains list. Supports exact domains and wildcard subdomain patterns (*.example.com).
3. User submits a URL or file -- the widget requests an invisible Turnstile challenge token.
4. Token exchange -- the widget sends the Turnstile token to POST /v1/widget/{widget_id}/token and receives a JWT (1-hour expiry) plus a refresh token cookie (7-day expiry).
5. Conversion -- the widget calls the conversion endpoint with the JWT.
6. Result -- the API returns a JSON response with a presigned_url. The widget displays a download link.
7. Timeout recovery -- if the conversion exceeds reverse-proxy timeout limits, the widget polls GET /v1/convert/status/{job_id} using the pre-generated job ID.

Automatic Token Refresh#

The widget never stops working due to expired authentication:

• On the initial conversion, the API issues both a JWT (1-hour expiry) and a refresh token (7-day expiry, httpOnly cookie).
• On subsequent conversions, the widget first attempts to refresh the JWT via POST /v1/widget/{widget_id}/refresh using the refresh token cookie -- no Turnstile challenge required.
• If the refresh token itself has expired (after 7 days of inactivity), the widget falls back to a new Turnstile challenge.
• The refresh token is rotated on every refresh -- each refresh issues a new 7-day cookie.

This means a widget visitor who converts every few days will never see a Turnstile challenge after the first one.

Widget Endpoints#

Configuration#

Retrieves the configuration for a specific widget. No authentication required.

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",
    "widget_branding": true
}

Token Exchange#

Exchanges a Turnstile challenge token for a JWT. Sets a refresh token cookie.

POST /v1/widget/{widget_id}/token
X-Parent-Origin: https://your-website.com
Content-Type: application/json

{
    "turnstile_token": "cloudflare-challenge-response-token"
}

Response:

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Also sets an httpOnly refresh_token cookie (7-day expiry, Secure, SameSite=none).

Token Refresh#

Refreshes an expired JWT using the httpOnly refresh token cookie. No Turnstile challenge required.

POST /v1/widget/{widget_id}/refresh
X-Parent-Origin: https://your-website.com

No request body needed -- the refresh token is read from the cookie automatically.

Response:

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
}

The refresh token cookie is rotated on each refresh (new 7-day cookie issued).

Error responses: - 401 -- no refresh token cookie or refresh token expired - 403 -- refresh token does not match the widget's project, or domain not authorized - 404 -- widget not found or deactivated

Conversion Response#

Both URL-based and file-based widget conversions return a consistent JSON response with a presigned download URL:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 8.5,
    "job_id": "client-generated-uuid"
}

The widget uses the presigned_url to display a download link. Presigned URLs expire after 15 minutes.

Widget conversion restrictions: - Single URL / single file only - Synchronous mode only (no async or batch) - No webhook callbacks or notification emails - Endpoint restricted to the one configured for the widget

Widget Branding#

Plans that include widget branding display a small "Powered by Enconvert" badge at the bottom of the widget. This is controlled by the widget_branding field on the subscription plan:

The branding badge links to https://enconvert.com and is styled to be unobtrusive -- small text below the widget form with reduced opacity.

To remove branding, upgrade to a Pro or Enterprise plan.

Widget Management#

Widgets are managed through the Enconvert dashboard or the backend API:

Embed Code Reference#

Standard HTML#

<script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>

The script: - Creates a sandboxed iframe (allow-scripts allow-same-origin allow-forms allow-popups) - Sets width: 100%, initial height 400px, no border - Enables clipboard-write permission - Uses lazy loading - Listens for Enconvert:resize messages to auto-adjust height

WordPress Shortcode#

If you use the Enconvert WordPress plugin, embed widgets using the shortcode:

[enconvert_widget id="your-widget-id"]

Style Customization#

Customize the widget appearance via query parameters on the embed script URL or the iframe source:

Iframe Communication#

The widget communicates with the parent page via postMessage. Listen for these events on the parent page:

Example: Listening for Events#

window.addEventListener("message", function(e) {
    if (!e.data || !e.data.type) return;

    if (e.data.type === "Enconvert:conversion:complete") {
        console.log("Conversion done:", e.data.data.url);
    }

    if (e.data.type === "Enconvert:conversion:error") {
        console.error("Conversion failed:", e.data.data.error);
    }
});

Security#

Frequently asked questions#

How do I embed a file converter widget on my website?#

Create a widget in the Enconvert dashboard (Dashboard > Widgets > Create Widget), then add one script tag to your page: <script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>. If your site runs WordPress, you can use the [enconvert_widget id="your-widget-id"] shortcode from the Enconvert WordPress plugin instead.

Do I need to expose an API key to embed a conversion widget?#

No. The embed code contains only the widget ID — an internal public API key is auto-generated for each widget, restricted to its configured endpoint and allowed domains, and is never visible in your frontend code.

How does the widget authenticate users without an API key?#

The widget requests an invisible Cloudflare Turnstile challenge and exchanges it at POST /v1/widget/{widget_id}/token for a JWT with 1-hour expiry plus an httpOnly refresh token cookie with 7-day expiry. Subsequent conversions refresh the JWT via POST /v1/widget/{widget_id}/refresh with no new challenge, and the refresh token is rotated on every refresh.

Can I restrict which domains can use my embedded widget?#

Yes. Each widget has an allowed-domains list that supports exact domains and wildcard subdomains like *.example.com, validated server-side on token issuance, with frame-ancestors CSP headers restricting which pages can embed the iframe.

How do I remove the Powered by Enconvert badge from the widget?#

The badge is controlled by the widget_branding field on your subscription plan: Free and Starter plans display it, while Pro and Enterprise plans hide it. Upgrade to a Pro or Enterprise plan to remove the branding.