Authentication

URLpipe authenticates every request with an HTTP bearer token. The token is your project's API key — there is nothing else to configure: no OAuth flow, no signed requests, no session to keep alive.

Sending your API key

Add an Authorization header with the value Bearer YOUR_API_KEY to every request. The scheme keyword Bearer is required, followed by a single space and then the key exactly as issued — no quotes, and no extra whitespace. Requests without a valid key are rejected with 401 Unauthorized before any work is done, so a rejected request never counts against your quota.

curl -X POST https://urlpipe.dev/markdown \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

const res = await fetch("https://urlpipe.dev/markdown", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.URLPIPE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
})

import os, requests

res = requests.post(
    "https://urlpipe.dev/markdown",
    headers={"Authorization": f"Bearer {os.environ['URLPIPE_API_KEY']}"},
    json={"url": "https://example.com"},
)

Testing your key

The quickest way to confirm a key works is to send any real request — the /markdown call above against a page you control is a good choice. A 200 (or a 422 about the URL itself) means the key authenticated; a 401 means the header never reached us in a form we accept. When you see a 401, check that the header name is exactly Authorization, that the value starts with Bearer , and that no proxy or framework is stripping or rewriting the header in transit.

How keys are scoped

Each API key belongs to a single project. A project owns its own request history and draws on its organization's monthly quota. Using separate projects per app or environment keeps history clean and lets you rotate one key without disturbing the others. A common setup is one project per environment — staging and production — so a leaked staging key can be rotated without touching live traffic, and each environment's usage shows up separately in the dashboard.

Finding and rotating your key

Your key is emailed to you when a project is created, and is always visible in the dashboard under Settings → API key. If a key is ever exposed, rotate it from the same screen — the old key stops working immediately and a new one takes its place. Because rotation is instant and irreversible, deploy the new key to your servers first (or in the same release) so in-flight requests don't start failing with 401.

Keeping your key secure

Your API key is a secret: anyone who has it can spend your quota and read whatever your account can. Treat it like a password.

• Send every request over HTTPS — never plain HTTP, which exposes the key in transit.
• Keep the key server-side. Never embed it in browser JavaScript, mobile apps, or any code shipped to users, where it can be extracted.
• Load it from an environment variable or a secrets manager. Don't hard-code it in source or commit it to version control — scanners harvest public repositories within minutes.
• Use a distinct key per environment so you can rotate one without affecting the others.
• Rotate immediately if a key is ever exposed, and periodically as routine hygiene.

Authentication errors

Two things cause a 401:

• The Authorization header is missing.
• The token doesn't match any active project key.

Everything else — a bad URL, a page that's too big, a timeout — is a 422 with a descriptive body. See Errors for the full list.