# Embed: Private pages and proxy

## Table of Contents

- [The embed URL is public](#the-embed-url-is-public)
- [Embed an authenticated dashboard PRO](#embed-an-authenticated-dashboard-pro)
  - [CLI Microlink API example](#cli-microlink-api-example)
  - [cURL Microlink API example](#curl-microlink-api-example)
  - [JavaScript Microlink API example](#javascript-microlink-api-example)
  - [Python Microlink API example](#python-microlink-api-example)
  - [Ruby Microlink API example](#ruby-microlink-api-example)
  - [PHP Microlink API example](#php-microlink-api-example)
  - [Golang Microlink API example](#golang-microlink-api-example)
- [Front public embeds with a proxy server](#front-public-embeds-with-a-proxy-server)
- [Embed sites blocked by antibot systems PRO](#embed-sites-blocked-by-antibot-systems-pro)
  - [CLI Microlink API example](#cli-microlink-api-example-1)
  - [cURL Microlink API example](#curl-microlink-api-example-1)
  - [JavaScript Microlink API example](#javascript-microlink-api-example-1)
  - [Python Microlink API example](#python-microlink-api-example-1)
  - [Ruby Microlink API example](#ruby-microlink-api-example-1)
  - [PHP Microlink API example](#php-microlink-api-example-1)
  - [Golang Microlink API example](#golang-microlink-api-example-1)
- [Geofenced content](#geofenced-content)
- [When private embeds still fail](#when-private-embeds-still-fail)
- [Next step](#next-step)

---

Most embeds are for public pages. The hard cases are private dashboards, region-locked products, and sites that block headless browsers. Both require

PRO

features — `headers`, `x-api-header-*`, and `proxy` — plus extra discipline because embed URLs are public by nature.

The shared patterns live in [private pages patterns](https://microlink.io/docs/guides/common/private-pages) and [proxy patterns](https://microlink.io/docs/guides/common/proxy). This page covers the embed-specific setup.

## The embed URL is public

Whatever you put in an embed URL ends up in HTML, browser devtools, server logs, social previews, and downstream caches. That changes the threat model:

| Approach                                               | Safe in public embed URLs?                          |
| ------------------------------------------------------ | --------------------------------------------------- |
| `headers={ 'accept-language': 'es-ES' }` (locale-only) | Yes — value is non-sensitive                        |
| `headers={ 'cookie': '...' }` (sensitive)              | **No** — exposes credentials                        |
| `x-api-header-cookie: ...` request header              | Yes — sent server-to-server, never in the embed URL |
| `proxy=https://user:pass@...` query param              | **No** — leaks proxy credentials                    |
| `proxy` set inside an SDK call from the server         | Yes — never reaches the browser                     |

The rule: only **non-sensitive** values belong in the embed URL. Everything else stays server-side, behind a backend that proxies the call to Microlink.

## Embed an authenticated dashboard PRO

Use `x-api-header-*` to forward the cookie or bearer token without exposing it:

```bash
curl-Ghttps://pro.microlink.io\

-durl=https://app.example.com/dashboard\

-dscreenshot=true\

-dembed=screenshot.url\

-dmeta=false\

-H'x-api-key: YOUR_API_TOKEN'\

-H'x-api-header-cookie: session=abc123'
```

The response is the screenshot bytes — usable as an `<img src>` in an internal portal or a logged-in user's email. The cookie never reaches the browser because the request lives on your backend.

For non-sensitive values like locale or accept-language, the URL-based `headers` parameter is fine:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://example.com/pricing' URL with 'screenshot', 'meta', 'headers', 'embed' & 'apiKey' API parameters:

### CLI Microlink API example

```bash
microlink https://example.com/pricing&screenshot&headers.Accept-Language=es-ES&embed=screenshot.url --api-key YOUR_API_TOKEN
```

### cURL Microlink API example

```bash
curl -G "https://pro.microlink.io" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d "url=https://example.com/pricing" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "headers.Accept-Language=es-ES" \
  -d "embed=screenshot.url"
```

### JavaScript Microlink API example

```javascript
import createClient from 'microlink.io'

const microlink = createClient({ apiKey: "YOUR_API_TOKEN" })

const data = await microlink.screenshot('https://example.com/pricing', {
  headers: {
    "x-api-header-accept-language": "es-ES"
  }
})
```

### Python Microlink API example

```python
import requests

url = "https://pro.microlink.io/"

querystring = {
    "url": "https://example.com/pricing",
    "screenshot": "true",
    "meta": "false",
    "headers.Accept-Language": "es-ES",
    "embed": "screenshot.url"
}

headers = {
    "x-api-key": "YOUR_API_TOKEN"
}

response = requests.get(url, params=querystring, headers=headers)

print(response.json())
```

### Ruby Microlink API example

```ruby
require 'uri'
require 'net/http'

base_url = "https://pro.microlink.io/"

params = {
  url: "https://example.com/pricing",
  screenshot: "true",
  meta: "false",
  headers.Accept-Language: "es-ES",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['x-api-key'] = "YOUR_API_TOKEN"
response = http.request(request)

puts response.body
```

### PHP Microlink API example

```php
<?php

$baseUrl = "https://pro.microlink.io/";

$params = [
    "url" => "https://example.com/pricing",
    "screenshot" => "true",
    "meta" => "false",
    "headers.Accept-Language" => "es-ES",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_TOKEN"
    ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}
```

### Golang Microlink API example

```
package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://pro.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://example.com/pricing")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("headers.Accept-Language", "es-ES")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("x-api-key", "YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

```javascript
importcreateClientfrom'microlink.io'

constmicrolink=createClient({apiKey:"YOUR_API_TOKEN"})

constdata=awaitmicrolink.screenshot('https://example.com/pricing',{

headers:{

"x-api-header-accept-language":"es-ES"

}

})
```

The locale-aware capture is rendered for an embedding without leaking secrets.

## Front public embeds with a proxy server

When the embed URL must be visible (a public OG image, a marketing card) but the request needs a key or cookies, run your own proxy:

- [@microlink/proxy](https://github.com/microlinkhq/proxy) for self-hosted Node.js / Express.
- [@microlink/edge-proxy](https://github.com/microlinkhq/edge-proxy) for Cloudflare Workers and edge runtimes.

Your public URL becomes `https://my-app.example.com/og?slug=hello`. The proxy converts that to a Microlink call with the API key and any `x-api-header-*` it needs, then streams the response back. The browser never sees the credentials.

For the architecture in detail, see [private pages patterns](https://microlink.io/docs/guides/common/private-pages).

## Embed sites blocked by antibot systems PRO

If the target page returns a CAPTCHA, an antibot challenge, or `EPROXYNEEDED`, you need a proxy.

Pro plans include **automatic proxy resolution** — the API detects the antibot provider and routes through the right pool without you setting `proxy` at all:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://difficult-target.example' URL with 'screenshot', 'meta', 'embed' & 'apiKey' API parameters:

### CLI Microlink API example

```bash
microlink https://difficult-target.example&screenshot&embed=screenshot.url --api-key YOUR_API_TOKEN
```

### cURL Microlink API example

```bash
curl -G "https://pro.microlink.io" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d "url=https://difficult-target.example" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "embed=screenshot.url"
```

### JavaScript Microlink API example

```javascript
import createClient from 'microlink.io'

const microlink = createClient({ apiKey: "YOUR_API_TOKEN" })

const data = await microlink.screenshot('https://difficult-target.example')
```

### Python Microlink API example

```python
import requests

url = "https://pro.microlink.io/"

querystring = {
    "url": "https://difficult-target.example",
    "screenshot": "true",
    "meta": "false",
    "embed": "screenshot.url"
}

headers = {
    "x-api-key": "YOUR_API_TOKEN"
}

response = requests.get(url, params=querystring, headers=headers)

print(response.json())
```

### Ruby Microlink API example

```ruby
require 'uri'
require 'net/http'

base_url = "https://pro.microlink.io/"

params = {
  url: "https://difficult-target.example",
  screenshot: "true",
  meta: "false",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['x-api-key'] = "YOUR_API_TOKEN"
response = http.request(request)

puts response.body
```

### PHP Microlink API example

```php
<?php

$baseUrl = "https://pro.microlink.io/";

$params = [
    "url" => "https://difficult-target.example",
    "screenshot" => "true",
    "meta" => "false",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_TOKEN"
    ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}
```

### Golang Microlink API example

```
package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://pro.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://difficult-target.example")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("x-api-key", "YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

```javascript
importcreateClientfrom'microlink.io'

constmicrolink=createClient({apiKey:"YOUR_API_TOKEN"})

constdata=awaitmicrolink.screenshot('https://difficult-target.example')
```

On a Pro plan, the API quietly resolves the antibot when it detects one. The `x-fetch-mode` response header will be prefixed with `proxy-`.

You can also pass your own proxy URL when you have a residential or country-specific service:

```js
importcreateClientfrom'microlink.io'

constmicrolink=createClient()

const{url}=awaitmicrolink.screenshot('https://example.com/pricing',{

proxy:process.env.PROXY_URL

})

returnurl// hand this to your embed renderer
```

Keep that call server-side — never expose the `proxy=` param in a public embed URL.

For the full proxy reference (when, how, and how to verify), see [proxy patterns](https://microlink.io/docs/guides/common/proxy).

## Geofenced content

A common embed use case: a product whose homepage shows different prices per country, and you want each region's preview cached separately. Combine `proxy` (for the IP region) with a content-hash cache buster (so each region cache is independent):

```js
asyncfunctionregionalEmbed(region){

constproxy=PROXIES[region]// e.g. 'https://user:pass@us-proxy.example.com:8080'

const{url}=awaitmicrolink.screenshot('https://example.com/pricing',{

proxy

})

returnurl

}
```

Render the resulting URL into your `<meta property="og:image">` for that locale. Pair with `ttl: '1d'` and `staleTtl: 0` so each region's variant stays warm. See [geolocation patterns](https://microlink.io/docs/guides/common/proxy#geolocation-target-region-specific-content).

## When private embeds still fail

If `x-api-header-*` and `proxy` are both set and the embed still returns wrong content:

- Confirm the cookie / token has not expired. Authenticated previews are only as fresh as the credential.
- Check `x-fetch-mode` — anything other than `proxy-*` means the proxy did not engage.
- Look for `EPROXYNEEDED` or `EAUTH` in the response body. See [error codes](https://microlink.io/docs/api/basics/error-codes).

For the rest, continue to [troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting).

## Next step

For debugging missing iframes, broken images, and provider-specific quirks, see [troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting).