How to Generate PDFs from Authenticated Pages

Overview

This guide explains how to use our HTML to PDF API to generate PDFs from pages that require you to sign in. Depending on how the page is protected, you can pass HTTP Basic Authentication credentials, an Authorization header, or a session cookie.

Protected vs private URLs

PDFGate renders pages from its own servers, so the URL must be reachable from the public internet. What matters is where the page is hosted, not whether it requires a login:

• Protected public URL: the page is on the internet but requires credentials, for example https://app.example.com/reports/42. This guide covers these pages.
• Private network URL: the page is only reachable from your machine, office network, or VPN, for example localhost, an intranet hostname, or a private IP address. PDFGate can't reach these pages, even with valid credentials.

For pages on a private network, render the HTML on your own server and send it with the html parameter instead of url.

Basic Authentication

Use the authentication parameter when the page responds with an HTTP authentication challenge, the browser dialog that asks for a username and password.

• url: The URL of the page you want to convert.
• authentication.username: The username used to authenticate.
• authentication.password: The password used to authenticate.

1curl --request POST \2  --url https://api.pdfgate.com/generate/pdf \3  --header 'Authorization: Bearer YOUR_API_KEY' \4  --header 'Content-Type: application/json' \5  --data '{6    "url": "https://httpbin.org/basic-auth/user/passwd",7    "authentication": {8      "username": "user",9      "password": "passwd"10    }11  }' \12  -o output.pdf

If the page responds with 401, or any other status of 400 or above, the request fails with a 422 error instead of returning a PDF.

Authorization header

If your application accepts a bearer token or API key, send it with the httpHeaders parameter. The Authorization header in the request headers authenticates you with PDFGate; the one inside httpHeaders is sent to the page you are converting.

1curl --request POST \2  --url https://api.pdfgate.com/generate/pdf \3  --header 'Authorization: Bearer YOUR_API_KEY' \4  --header 'Content-Type: application/json' \5  --data '{6    "url": "https://app.example.com/reports/42",7    "httpHeaders": {8      "Authorization": "Bearer YOUR_APP_ACCESS_TOKEN"9    },10    "waitForSelector": "#report-loaded"11  }' \12  -o output.pdf

Session cookies

If your application uses cookie-based sessions, send the session cookie as a Cookie header in httpHeaders. Create a dedicated session for PDF generation rather than reusing a user's browser session.

1curl --request POST \2  --url https://api.pdfgate.com/generate/pdf \3  --header 'Authorization: Bearer YOUR_API_KEY' \4  --header 'Content-Type: application/json' \5  --data '{6    "url": "https://app.example.com/reports/42",7    "httpHeaders": {8      "Cookie": "session_id=YOUR_SESSION_ID"9    },10    "waitForSelector": "#report-loaded"11  }' \12  -o output.pdf

httpHeaders are sent with every request the page makes, including requests to third-party domains such as CDNs or analytics. Use short-lived tokens or sessions that only grant access to the pages you need to convert.

Unlike authentication, a token or cookie that is invalid or expired doesn't fail the request: most applications redirect to their login page, and that page is converted instead. Set waitForSelectorto an element that only appears when you are signed in, as in the examples above. If it doesn't appear within 30 seconds, the request fails instead of returning the wrong page.

Login forms and SSO

PDFGate can't type credentials into a login form or complete single sign-on (SSO) flows such as OAuth redirects, SAML, or multi-factor authentication. For pages behind these flows:

• Add a server-side way to access the page with a token, such as a signed, short-lived URL or a token accepted in the Authorization header, and pass it as shown above.
• Or render the page on your own server and send the resulting HTML with the html parameter.

Additional Notes

The authentication parameter only works with url. httpHeaders also work with html, where they are sent with requests for images, stylesheets, and other resources the HTML loads.

For a full list of supported options, see the HTML to PDF API Reference.