Blink PDF API Authentication: Keys, Headers & Errors

Every render or template request to the Blink PDF REST API must include an API key. REST uses API key authentication — you pass your key in the x-api-key header on authenticated requests. There are no sessions or cookies on the REST surface. The MCP server accepts the same bp_* keys (as Authorization: Bearer or x-api-key) and also supports OAuth 2.1 + PKCE for remote agent connectors — see Connect a Client.

Get your API key

API keys are created and managed in the Blink PDF dashboard.

Go to app.blinkpdf.io and sign in. If you don’t have an account yet, sign up for free — no credit card required.

Open the API Keys section

From the dashboard sidebar, click API Keys. Any keys you’ve already created are listed here (the secret portion is masked after creation).

Create a new key

Click Create new key, give it a descriptive name (for example, production-invoices or staging-test), and confirm. Your full API key is displayed once — copy it now.

Never share or expose your API key. Treat it like a password. If you accidentally commit a key to a public repository or expose it in client-side code, rotate it immediately from the dashboard — your old key will stop working the moment you do.

Pass your key in requests

Include your API key in the x-api-key header of every render or template request:

x-api-key: bp_...

Here’s a complete example:

curl

curl https://api.blinkpdf.io/v1/render \
  --request POST \
  --header 'Accept: application/pdf' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: bp_xxxxxxxxxxxxxxxxxxxx' \
  --data '{"markdown": "# Hello\n\nWorld"}'

Key format

API keys always start with the prefix bp_ followed by a unique alphanumeric string. If your key doesn’t start with bp_, double-check that you copied the full key from the dashboard.

Prefix	Environment
`bp_`	Production

All keys are scoped to your account and inherit your plan’s rate limits and monthly render quota.

Use environment variables

Never hardcode your API key in source files. Store it in an environment variable and read it at runtime. This prevents accidental exposure through version control, logs, or error messages.

Set the environment variable

export BLINKPDF_API_KEY="bp_xxxxxxxxxxxxxxxxxxxx"

For persistent configuration, add this line to your shell profile (.bashrc, .zshrc) or use a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform’s secret store.

Read it in your code

import os
import requests

api_key = os.environ["BLINKPDF_API_KEY"]  # Raises KeyError if not set

response = requests.post(
    "https://api.blinkpdf.io/v1/render",
    headers={
        "x-api-key": api_key,
        "Accept": "application/pdf",
        "Content-Type": "application/json",
    },
    json={"markdown": "# Hello, world!"},
)

response.raise_for_status()

const apiKey = process.env.BLINKPDF_API_KEY;

if (!apiKey) {
  throw new Error("BLINKPDF_API_KEY environment variable is not set");
}

const response = await fetch("https://api.blinkpdf.io/v1/render", {
  method: "POST",
  headers: {
    "x-api-key": apiKey,
    Accept: "application/pdf",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ markdown: "# Hello, world!" }),
});

if (!response.ok) {
  throw new Error(`${response.status} ${response.statusText}`);
}

# Read the key from the environment rather than pasting it inline
curl https://api.blinkpdf.io/v1/render \
  --request POST \
  --header 'Accept: application/pdf' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${BLINKPDF_API_KEY}" \
  --data '{"markdown": "# Hello\n\nWorld"}'

Common authentication errors

401 Unauthorized

You’ll receive a 401 response if the x-api-key header is missing, malformed, or contains an invalid key.

HTTP/1.1 401 Unauthorized

Common causes and fixes:

Cause	Fix
Header not included in the request	Add `x-api-key: bp_...` to every authenticated render or template request
Key was rotated or deleted	Create a new key in the dashboard and update your configuration
Key copied with extra whitespace	Trim leading/trailing spaces from the key string
Key sent in the wrong header	Send the key in `x-api-key` — Blink PDF does not use the `Authorization` header

402 Payment Required

A 402 response means your API key is valid, but your plan’s spend cap has been reached. Usage beyond the included volume is paused until the next billing period. The response body is { "error": "spend_cap_reached", "detail": "..." }.

HTTP/1.1 402 Payment Required

Common causes and fixes:

Cause	Fix
Spend cap reached for the period	Raise the spend cap or upgrade your plan in the dashboard, or wait for the next billing period
Included volume exhausted	Review your current plan limits and usage in the dashboard

You can monitor your remaining quota and usage at any time from the Usage section of your dashboard.

Security best practices

Rotate keys regularly. Create a new key and retire the old one on a schedule, or any time team membership changes.
Use one key per environment. Maintain separate keys for development, staging, and production so you can rotate or revoke them independently.
Use one key per service. If multiple services call the Blink PDF API, give each its own key. This limits the blast radius if one key is compromised.
Never log the key. Avoid printing the full x-api-key header in application logs or error messages.
Restrict access at the infrastructure level. Where possible, use a secrets manager or environment injection rather than .env files checked into source control.

Next steps

Quickstart

If you haven’t made your first API call yet, start here.

API Reference

Explore all parameters and headers for the POST /v1/render endpoint.

Get Started

Core Concepts

Guides

MCP Server

Configuration

Plans & Limits

Help

Blink PDF API Authentication: Keys, Headers & Errors

Get your API key

Pass your key in requests

Key format

Use environment variables

Set the environment variable

Read it in your code

Common authentication errors

401 Unauthorized

402 Payment Required

Security best practices

Next steps

Quickstart

API Reference

​Get your API key

​Pass your key in requests

​Key format

​Use environment variables

​Set the environment variable

​Read it in your code

​Common authentication errors

​401 Unauthorized

​402 Payment Required

​Security best practices

​Next steps

Quickstart

API Reference

Get your API key

Pass your key in requests

Key format

Use environment variables

Set the environment variable

Read it in your code

Common authentication errors

401 Unauthorized

402 Payment Required

Security best practices

Next steps