Authentication

When generating PDFs or images from URLs, your target page may be behind authentication. cloudlayer.io supports two authentication methods for accessing protected pages:

• Basic Auth — HTTP Basic Authentication using a username and password
• Cookie Auth — Session cookies that establish an authenticated user state

Both methods work with all URL-based endpoints (/url/pdf, /url/image).

Basic Auth

If your URL is protected behind HTTP Basic Authentication, pass the credentials using the authentication object.

JSON Payload

{
  "url": "https://internal.example.com/dashboard",
  "authentication": {
    "username": "admin",
    "password": "secretpassword"
  }
}

Parameters

cURL Example

curl --request POST \
  --url https://api.cloudlayer.io/v2/url/pdf \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "url": "https://internal.example.com/dashboard",
    "authentication": {
      "username": "admin",
      "password": "secretpassword"
    },
    "async": false
  }'

JavaScript Example

const response = await fetch("https://api.cloudlayer.io/v2/url/pdf", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR-API-KEY>",
  },
  body: JSON.stringify({
    url: "https://internal.example.com/dashboard",
    authentication: {
      username: "admin",
      password: "secretpassword",
    },
    async: false,
  }),
});

const result = await response.json();
console.log(result.assetUrl);

Python Example

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/pdf",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>",
    },
    json={
        "url": "https://internal.example.com/dashboard",
        "authentication": {
            "username": "admin",
            "password": "secretpassword",
        },
        "async": False,
    },
)

result = response.json()
print(result["assetUrl"])

Practical Example: Capturing a Protected Dashboard

A common use case is generating PDF reports from internal dashboards that require login:

{
  "url": "https://analytics.yourcompany.com/reports/monthly",
  "authentication": {
    "username": "report-bot",
    "password": "bot-secret-key"
  },
  "format": "letter",
  "landscape": true,
  "printBackground": true,
  "margin": {
    "top": "0.5in",
    "bottom": "0.5in",
    "left": "0.5in",
    "right": "0.5in"
  },
  "waitUntil": "networkidle0",
  "delay": 2000,
  "async": false
}

This configuration:

1. Authenticates to the dashboard with Basic Auth credentials
2. Waits for all network requests to complete (networkidle0)
3. Adds an extra 2-second delay for any JavaScript-rendered charts to finish
4. Generates a letter-sized landscape PDF with backgrounds and custom margins

Cookie Auth

For sites that use session-based authentication (login forms, OAuth, etc.), you can pass session cookies to establish an authenticated state before the page is loaded.

JSON Payload

{
  "url": "https://app.example.com/account",
  "cookies": [
    {
      "name": "_session_id",
      "value": "ad9a8u90f0df7d87fdas9fa892342",
      "domain": "app.example.com",
      "path": "/",
      "expires": 1768752280,
      "httpOnly": true,
      "secure": true
    }
  ]
}

Cookie Parameters

cURL Example

curl --request POST \
  --url https://api.cloudlayer.io/v2/url/pdf \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "url": "https://app.example.com/account",
    "cookies": [
      {
        "name": "_session_id",
        "value": "ad9a8u90f0df7d87fdas9fa892342",
        "domain": "app.example.com",
        "path": "/",
        "expires": 1768752280,
        "httpOnly": true
      }
    ],
    "async": false
  }'

JavaScript Example

const response = await fetch("https://api.cloudlayer.io/v2/url/pdf", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR-API-KEY>",
  },
  body: JSON.stringify({
    url: "https://app.example.com/account",
    cookies: [
      {
        name: "_session_id",
        value: "ad9a8u90f0df7d87fdas9fa892342",
        domain: "app.example.com",
        path: "/",
        httpOnly: true,
      },
    ],
    async: false,
  }),
});

const result = await response.json();
console.log(result.assetUrl);

Python Example

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/pdf",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>",
    },
    json={
        "url": "https://app.example.com/account",
        "cookies": [
            {
                "name": "_session_id",
                "value": "ad9a8u90f0df7d87fdas9fa892342",
                "domain": "app.example.com",
                "path": "/",
                "httpOnly": True,
            },
        ],
        "async": False,
    },
)

result = response.json()
print(result["assetUrl"])

Multiple Cookies

You can pass multiple cookies in a single request to replicate a full browser session:

{
  "url": "https://app.example.com/dashboard",
  "cookies": [
    {
      "name": "_session_id",
      "value": "abc123def456",
      "domain": "app.example.com",
      "path": "/",
      "httpOnly": true
    },
    {
      "name": "cookie_consent",
      "value": "accepted",
      "domain": "app.example.com",
      "path": "/"
    },
    {
      "name": "theme",
      "value": "dark",
      "domain": "app.example.com",
      "path": "/"
    }
  ]
}

How to Obtain Session Cookies

To capture cookies from an authenticated session:

1. Log in to the target site in your browser.
2. Open Developer Tools (F12 or Ctrl+Shift+I).
3. Go to the Application tab (Chrome) or Storage tab (Firefox).
4. Navigate to Cookies and select the site’s domain.
5. Copy the relevant cookie name/value pairs (look for session identifiers like _session_id, connect.sid, PHPSESSID, etc.).

Note: Session cookies typically have a limited lifespan. For automated workflows, consider using a dedicated API token or service account instead of short-lived session cookies.

Security and Privacy

cloudlayer.io takes authentication credentials seriously:

• Credentials are never stored. Authentication usernames, passwords, and cookie values are redacted from all logs and database records.
• Activity logs show ... in place of any sensitive information.
• Use HTTPS URLs whenever passing authentication credentials to ensure they are encrypted in transit to the target page.
• Use short-lived credentials or service accounts with minimal permissions for automated workflows.

For more details, see the Privacy & Data Handling guide.

Tips

• Basic Auth is simpler and preferred when the target site supports it. Cookie auth requires managing session state.
• Use waitUntil: "networkidle0" with authenticated pages to ensure all authenticated API calls complete before capture.
• Add a delay (in milliseconds) if the page has JavaScript-heavy content that takes time to render after authentication.
• Test your authentication by first trying the URL in a browser with the same credentials to verify the page loads correctly.
• For single-page apps (SPAs), cookie auth combined with waitForSelector is often more reliable than a simple delay.