How to Authenticate Microlink Screenshot Requests with an API Key

To authenticate a Microlink Pro screenshot request, send a GET request to https://pro.microlink.io, put your Microlink Pro token in the x-api-key request header, set url to the page you want to capture, and set screenshot=true. A basic screenshot of a public page can instead use https://api.microlink.io without a key. Keep the Pro token on your server; do not expose it in frontend code or a public URL.

Choose the right endpoint

Use case	Endpoint	Microlink API key
Basic screenshot of a public page	`https://api.microlink.io`	Not required
Pro account quota or Pro features	`https://pro.microlink.io`	Send as `x-api-key`
Forward headers to a target page behind login	`https://pro.microlink.io`	Required, plus separate target credentials

Microlink’s current overview says the free endpoint allows 25 requests per day. Quotas and plan details can change, so confirm the current limits in Microlink’s [API overview](https://microlink.io/docs/api/overview). A key is not required just because the output is a screenshot; use the Pro endpoint when your account or the feature you need requires it.

Make an authenticated screenshot request with cURL

This requests a screenshot from Microlink Pro and disables metadata in the response because only the screenshot is needed:

curl -G 'https://pro.microlink.io' \\
  -H 'x-api-key: YOUR_API_TOKEN' \\
  -d 'url=https://example.com' \\
  -d 'screenshot=true' \\
  -d 'meta=false'

Replace YOUR_API_TOKEN with a Pro token supplied securely to your server process. Do not commit a real token to source control. The command sends the token in an HTTP header, not in the URL. Consult Microlink’s [authentication guide](https://microlink.io/docs/api/authentication) for its current authentication details.

Use Python

Install the HTTP client with python -m pip install requests. This example reads the token from an environment variable, checks for an HTTP error, and writes the returned response body to a file:

import os
import requests

api_token = os.environ["MICROLINK_API_TOKEN"]
response = requests.get(
    "https://pro.microlink.io",
    headers={"x-api-key": api_token},
    params={
        "url": "https://example.com",
        "screenshot": "true",
        "meta": "false",
    },
    timeout=90,
)
response.raise_for_status()

with open("screenshot", "wb") as image_file:
    image_file.write(response.content)

Set MICROLINK_API_TOKEN in your deployment environment or secret manager before running the script. The response body is saved without assuming a file extension or image format. Check Microlink’s response documentation for the exact response shape and output handling required by your integration.

Use Node.js

This example uses the built-in fetch available in current Node.js releases. It obtains the token from the server environment, URL-encodes the query parameters, checks the HTTP status, and saves the response bytes:

import { writeFile } from 'node:fs/promises';

const apiToken = process.env.MICROLINK_API_TOKEN;
if (!apiToken) throw new Error('Set MICROLINK_API_TOKEN first');

const query = new URLSearchParams({
  url: 'https://example.com',
  screenshot: 'true',
  meta: 'false',
});

const response = await fetch(`https://pro.microlink.io?${query}`, {
  headers: { 'x-api-key': apiToken },
});
if (!response.ok) {
  throw new Error(`Microlink returned HTTP ${response.status}`);
}

const image = Buffer.from(await response.arrayBuffer());
await writeFile('screenshot', image);

Run it in a server environment where MICROLINK_API_TOKEN is set. For older Node.js versions without a built-in fetch, use a supported HTTP client and keep the same endpoint, header, and query parameters.

Keep the two kinds of credentials separate

There can be two independent credentials in a screenshot workflow:

Microlink API token: authenticates your application to Microlink. Send it in x-api-key.
Target-site credential: lets the capture access a page that requires a login. On Pro, Microlink documents forwarding target headers with the x-api-header- prefix.

For example, this request sends a Microlink token and forwards a session cookie to the target page. Use it only when your application is authorized to access that account and content:

curl -G 'https://pro.microlink.io' \\
  -H 'x-api-key: YOUR_API_TOKEN' \\
  -H 'x-api-header-cookie: session=SESSION_VALUE' \\
  -d 'url=https://app.example.com/dashboard' \\
  -d 'screenshot=true' \\
  -d 'meta=false'

For a target that expects a bearer token, the forwarded header has this form:

-H 'x-api-header-authorization: Bearer TARGET_ACCESS_TOKEN'

The x-api-header-cookie or x-api-header-authorization value is for the target website; it does not replace x-api-key. Microlink strips the prefix and forwards the resulting header to the target. Its authenticated-page guidance documents this pattern and says header forwarding is a Pro feature: [authenticated pages](https://microlink.io/docs/api/use-cases/scrape-private-page).

Do not put either credential in query parameters. URLs can be copied, logged, or exposed through monitoring systems. Keep them server-side, forward only credentials you are entitled to use, and avoid logging raw request headers.

Check that Pro authentication worked

Microlink documents the x-pricing-plan response header as a way to verify the plan handling an authenticated request. A successful Pro response can report pro. If you do not see the expected value, verify the endpoint, token, and account before debugging the target page.

For example, inspect headers with:

curl -sS -D - -o screenshot \\
  -G 'https://pro.microlink.io' \\
  -H 'x-api-key: YOUR_API_TOKEN' \\
  -d 'url=https://example.com' \\
  -d 'screenshot=true' \\
  -d 'meta=false'

The -D - option prints response headers; -o screenshot writes the body to a file. Do not share captured headers if they contain account or request details.

Options and request details

url identifies the page Microlink should visit. URL-encode it when constructing a request manually; cURL’s -G with -d, Python’s params, and JavaScript’s URLSearchParams do this for you.
screenshot=true asks for a screenshot. Authentication does not change the request method: it remains GET.
meta=false is optional and avoids requesting metadata when the screenshot is all you need.
x-api-key is an HTTP request header for Pro authentication. It is not a query parameter.
x-api-header-* headers forward selected request headers to the target site, such as cookies or authorization. They are separate from Microlink authentication and require Pro according to the private-page guide.

Use Microlink’s [API reference](https://microlink.io/docs/api) for other supported capture parameters and current response formats. Do not assume that an option used by another screenshot API has identical behavior in Microlink.

Security and deployment checklist

Store the Pro token in a server-side environment variable or secret manager.
Send it only in x-api-key over HTTPS to the Pro endpoint.
Do not embed the token in browser JavaScript, mobile app bundles, source maps, or public repositories.
Do not place tokens or target credentials in query strings.
If a browser feature needs screenshots, have your backend call Microlink. If using a proxy, restrict it to trusted domains and permitted operations so visitors cannot use it as an open relay.
Keep target-site credentials scoped and short-lived where possible, and do not capture or retain private content without authorization.

Troubleshooting

Symptom	Likely cause	What to check
Authentication fails or Pro request is rejected	Missing, malformed, expired, or incorrect token; wrong endpoint	Use `https://pro.microlink.io`, pass `x-api-key: YOUR_API_TOKEN`, and confirm the token belongs to a Pro account.
Request succeeds but does not appear to use Pro	Request reached the free endpoint or credentials were not sent as a header	Check the hostname and inspect `x-pricing-plan` in the response headers.
Screenshot shows a login page	The target session cookie is missing, expired, scoped to another domain, or not forwarded	Use Pro and the correct `x-api-header-cookie` or authorization header. Confirm the cookie’s domain and session validity.
Screenshot is taken before private content appears	The authenticated page renders asynchronously	Use Microlink’s documented `waitForSelector` option for an element that appears after authentication; verify the selector against the rendered page.
One user’s page appears in another user’s capture	Cache entries for the same URL may be shared	For multi-user captures, use a per-user `cacheKey` as described in Microlink’s private-page guidance.
Token appears in logs or shared links	Credential was placed in a URL or logged with request details	Move it to the `x-api-key` header, remove it from URLs, and redact secrets from logs.
Saved output cannot be opened as an image	The response may be an error body or another response form rather than image bytes	Check HTTP status and response headers before saving or serving the body as an image.
Free request quota is exhausted	The no-key endpoint has a limited daily allowance	Check Microlink’s current overview for quota and plan choices; use Pro if its quota or capabilities fit the workload.

Performance, reliability, and cost

Choose the free endpoint for occasional basic screenshots of public pages when its current quota is enough. Choose Pro when you need a Pro account’s higher quota or features such as proxy resolution, custom headers, configurable cache TTL, or forwarded target headers. Check Microlink’s current plan page before estimating cost because plan limits and pricing can change.

For reliability, set a client-side timeout appropriate to your application, handle non-success HTTP responses before treating a body as an image, and retry only transient failures with a limit and backoff. Avoid sending simultaneous duplicate captures when your workflow can reuse a completed result. A page behind login can fail independently of Microlink authentication if its session expires or the page’s JavaScript has not finished rendering.

Microlink’s overview publishes a screenshot P95 of 2.8 seconds and a 99.9% SLA on paid plans. These are vendor-stated figures, not independent measurements; check the overview and applicable plan terms before using them for capacity planning or an availability commitment.

Or skip the browser setup

If your goal is simply to get a screenshot from an API, [ScreenshotNeo](https://screenshotneo.com) is an alternative website screenshot API and MCP server. Its single GET request returns an image or PDF, and the [API documentation](https://screenshotneo.com/docs/) describes its request options.

curl -G "https://api.screenshotneo.com/v1/shot" \\
  -d access_key=YOUR_API_KEY \\
  --data-urlencode url=https://stripe.com \\
  -o shot.webp

Cookie banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. See the [ScreenshotNeo docs](https://screenshotneo.com/docs/) for options and setup, or [sign up free](https://screenshotneo.com/account/sign-up/) to start with 1,000 screenshots a month and no card.

FAQ

Do I need a Microlink API key for every screenshot?

No. Microlink’s standard endpoint supports basic public-page screenshots without a key. The Pro endpoint uses a token in x-api-key.

Can I use an API key from frontend JavaScript?

Do not expose a Pro token in client-side code. Call Microlink from your backend or use a proxy restricted to trusted domains.

The documented forwarding of target cookies and authorization headers is a Pro feature. The Microlink token and target-site login credential are separate.

How can I confirm the request used Pro?

Inspect the response’s x-pricing-plan header; Microlink documents pro as the expected value for an authenticated Pro request.