DEV Community

IronSoftware
IronSoftware

Posted on

Set HTTP Request Headers for PDF in C# (.NET Guide)

#dotnet #csharp

We generated PDFs from password-protected web pages. The rendering failed with 401 errors. Our web scraper needed authentication headers but IronPDF couldn't pass them through.

Custom HTTP request headers solved this. Here's how to pass headers when rendering URLs to PDF.

How Do I Set HTTP Request Headers for PDF Rendering?

Use the HttpRequestHeaders property with a dictionary:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer YOUR_TOKEN_HERE" },
    { "User-Agent", "MyApp/1.0" }
};

var pdf = renderer.RenderUrlAsPdf("https://api.example.com/report");
pdf.SaveAs("authenticated-report.pdf");
Enter fullscreen mode Exit fullscreen mode

The headers are sent with every HTTP request during PDF generation.

Why Would I Need Custom Headers?

Authentication: APIs require Bearer tokens or API keys
Session management: Passing cookies for logged-in content
Custom user agents: Bypassing bot detection
Proxy authentication: Corporate proxy credentials
Content negotiation: Requesting specific response formats
Rate limiting: Including API quota tracking headers

I use this for generating financial reports from internal dashboards that require SSO tokens.

How Do I Add Authorization Headers?

For API authentication:

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
};

var pdf = renderer.RenderUrlAsPdf("https://api.internal.com/dashboard");
pdf.SaveAs("dashboard.pdf");
Enter fullscreen mode Exit fullscreen mode

The Bearer token authenticates all requests. Works with OAuth2, JWT, and API key authentication.

Can I Set Multiple Headers at Once?

Yes. Add as many key-value pairs as needed:

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer token123" },
    { "User-Agent", "MyPdfBot/2.0" },
    { "Accept-Language", "en-US,en;q=0.9" },
    { "X-API-Key", "abc123xyz" },
    { "Referer", "https://yourapp.com" }
};
Enter fullscreen mode Exit fullscreen mode

All headers are applied to the request.

How Do I Pass Cookies?

Use the Cookie header:

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Cookie", "session_id=abc123; user_token=xyz789" }
};

var pdf = renderer.RenderUrlAsPdf("https://portal.example.com/dashboard");
Enter fullscreen mode Exit fullscreen mode

This passes session cookies to render logged-in content. I use this to generate PDFs of customer dashboards without requiring re-authentication.

What Headers Are Commonly Used?

Authorization: "Bearer token" or "Basic base64credentials"
User-Agent: Identifies your client (e.g., "MyApp/1.0")
Accept: Content type preference (e.g., "text/html")
Content-Type: Request body format (usually not needed for GET requests)
Referer: URL of the referring page
Cookie: Session and authentication cookies
X-Forwarded-For: Original client IP (for proxy scenarios)

I commonly use Authorization, User-Agent, and Cookie for our PDF generation pipeline.

How Do I Debug Header Issues?

Test your headers with httpbin.org first:

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "X-Test-Header", "MyValue" },
    { "Authorization", "Bearer test123" }
};

var pdf = renderer.RenderUrlAsPdf("https://httpbin.org/headers");
pdf.SaveAs("test-headers.pdf");
Enter fullscreen mode Exit fullscreen mode

Open test-headers.pdf. It shows all headers the server received. Verify your custom headers appear correctly.

Can I Set Headers Per Request?

No. Headers are set on the renderer instance and apply to all requests made during that PDF generation. If you need different headers for different PDFs, create separate renderer instances:

// Renderer for API A
var rendererA = new ChromePdfRenderer();
rendererA.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer tokenA" }
};

// Renderer for API B
var rendererB = new ChromePdfRenderer();
rendererB.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer tokenB" }
};

var pdfA = rendererA.RenderUrlAsPdf("https://api-a.com/report");
var pdfB = rendererB.RenderUrlAsPdf("https://api-b.com/report");
Enter fullscreen mode Exit fullscreen mode

Each renderer maintains its own header configuration.

How Do I Handle Basic Authentication?

Convert credentials to Base64:

var credentials = Convert.ToBase64String(
    System.Text.Encoding.UTF8.GetBytes("username:password")
);

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Authorization", $"Basic {credentials}" }
};

var pdf = renderer.RenderUrlAsPdf("https://protected-site.com");
Enter fullscreen mode Exit fullscreen mode

Basic auth works for legacy systems requiring username/password authentication.

Do Headers Apply to Embedded Resources?

Yes. Headers are sent for the main page AND all embedded resources (CSS, JavaScript, images). This is important for authenticated content where stylesheets and scripts are also behind authentication.

I discovered this when our rendered PDFs had broken styling. The CSS files required authentication too. Adding the Authorization header fixed it.

Can I Modify User-Agent to Avoid Bot Detection?

Yes:

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" }
};
Enter fullscreen mode Exit fullscreen mode

Some sites block requests with uncommon user agents. Setting a standard browser user agent helps.

How Do I Handle CORS and Cross-Origin Headers?

CORS is a browser security feature. IronPDF renders server-side and doesn't enforce CORS. You typically don't need cross-origin headers unless the target server specifically requires them.

If needed, add:

renderer.RenderingOptions.HttpRequestHeaders = new Dictionary<string, string>
{
    { "Origin", "https://yourapp.com" },
    { "Access-Control-Request-Method", "GET" }
};
Enter fullscreen mode Exit fullscreen mode

I've rarely needed this for PDF generation scenarios.

What If My Headers Get Rejected?

Check header format: Ensure no typos in header names
Verify authentication: Test the token/credentials separately
Inspect server requirements: Some servers require specific header combinations
Use httpbin.org: Verify headers are sent correctly

If the URL works in a browser but fails in IronPDF, capture the browser's request headers (Chrome DevTools Network tab) and replicate them exactly.

Written by Jacob Mellor, CTO at Iron Software. Jacob created IronPDF and leads a team of 50+ engineers building .NET document processing libraries.

Top comments (0)