← All posts

Web API Authentication Token Header: A Practical Guide

September 2, 2026

What Is a Web API Authentication Token Header?

A web API authentication token header is an HTTP header — almost always Authorization — that carries a credential proving your request is allowed to hit an endpoint. The server checks that credential and either processes the request or rejects it with a 401 or 403. There's no session cookie, no login form, no round trip — just a string attached to every request.

Despite that simplicity, an API token header is the single most common source of "why is my integration failing" tickets in developer tooling. Most of the time it's not a broken API — it's a malformed header. This article covers the exact syntax, the real-world patterns you'll encounter (Bearer, API key, Basic), working code in three languages, why headers beat query strings for token security, and a checklist for the 401/403 errors you'll actually hit in production.

The Authorization Header: Correct Syntax and Schemes

The format is rigid: Authorization: . One space separates the scheme from the credentials, and the scheme name is case-sensitive by convention even though HTTP header names themselves aren't. Get either piece wrong and most servers won't complain — they'll just quietly return a 401.

Three schemes cover almost every API you'll integrate with:

  • Bearer — Authorization: Bearer . Defined by RFC 6750 as part of the OAuth 2.0 spec, it's become the de facto standard for token-based APIs generally, not just OAuth flows. The WorkOS explainer on bearer tokens traces this origin and confirms the capitalized "Bearer" prefix is the documented convention, not a stylistic choice.
  • Basic — Authorization: Basic . Older, credential-based, rarely appropriate for modern token-issuing APIs, but still common in internal tooling and some legacy endpoints.
  • Digest — a challenge-response scheme that hashes credentials rather than sending them plainly. Occasionally seen in older infrastructure, but largely obsolete for public APIs.

The Authorization header bearer token pattern wins because the token is opaque, easy to rotate, and doesn't require re-sending a password on every call. Capitalization and spacing matter because the HTTP authentication header format is parsed literally by most server frameworks — bearer (lowercase) or Bearer: (missing space, extra colon) will often fail silently rather than throw a helpful error.

Bearer Token vs API Key: Which Header Should You Use?

Both live in a header and both authenticate a request, but they identify different things. A bearer token typically represents a user or session — issued after an authentication event and usually expiring. An API key typically represents an application or project — issued once, often long-lived, and used to attribute usage, enforce rate limits, or bill an account.

For Authorization Bearer token vs API key decisions in practice: if your API involves user-level permissions or session state, bearer tokens fit naturally. For service-to-service integrations — like a scraping or rendering API called from a backend job — an API key is often simpler and matches the actual security model of identifying the calling project, not a human user.

Many APIs sidestep the ambiguity with a custom X-API-Key header instead of overloading Authorization. This keeps API-key auth distinct from OAuth-style bearer flows and avoids confusing middleware that expects Authorization to always mean a session token. Neither approach is "more correct" — what matters is sending exactly the header name and format the API documents.

Code Examples: Sending an Auth Token in curl, JavaScript, and Python

A working API token header example in each of the three environments developers use most:

curl

curl https://api.example.com/v1/render \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript (fetch)

const response = await fetch("https://api.example.com/v1/render", {
  headers: {
    "Authorization": `Bearer ${process.env.API_TOKEN}`
  }
});

Python (requests)

import requests, os

headers = {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}
response = requests.get("https://api.example.com/v1/render", headers=headers)

If the API you're calling uses a custom key header instead, the pattern for how to send an API key in header form is nearly identical — swap the header name and drop the scheme prefix:

curl https://api.example.com/v1/render -H "X-API-Key: YOUR_KEY_HERE"

Always load tokens from environment variables or a secrets manager, never hardcode them in source — that's the first rule of any API authentication header best practices checklist.

Why Headers Beat Query Strings for Tokens

Putting a token in a URL — ?api_key=abc123 — feels convenient, but it's a documented anti-pattern. Query strings get logged by web servers, proxies, and CDNs by default; they're stored in browser history; and they leak via the Referer header to third-party domains when a page makes outbound links or requests. None of that happens with a header sent over HTTPS, which is encrypted in transit and generally excluded from access logs.

This is the core argument in OWASP-aligned guidance and echoed in the comparison of bearer tokens in headers versus API keys in query parameters: headers are the safer default, and query-string tokens should be treated as a legacy fallback at best, never a design choice for a new integration.

Debugging 401 and 403 Errors

When authentication fails, work through this in order:

  1. Missing or misspelled "Bearer" prefix — bearer, Bearer:, or a missing space all break parsing on most servers.
  2. Expired token — check issuance and expiry timestamps; a token valid yesterday isn't necessarily valid now.
  3. Wrong environment token — a live-mode token sent to a sandbox endpoint (or vice versa) fails even though the syntax is perfect.
  4. Trailing whitespace or stray quotes — copy-pasting from a .env file or dashboard often carries an invisible newline or quote character into the header value.
  5. 401 vs 403 — know the difference. A 401 means the server couldn't authenticate the request at all — the token is missing, malformed, or invalid. A 403 means authentication succeeded but the authenticated identity lacks permission for that specific resource or action. Treating a 403 as a token problem wastes debugging time — the fix is usually a permissions or plan issue, not a header issue.

Using This Pattern with Browsevra's API

Browsevra API authentication follows exactly this standard: every request carries your token in the Authorization header using the Bearer scheme, over HTTPS, with no credentials ever passed as query parameters. If you've followed the syntax and examples above, you already know how to authenticate against it.

For headless rendering specifically — screenshots, PDFs, HTML capture, or structured extraction — this token-per-request model means you can rotate keys, scope usage per project, and monitor consumption without managing sessions. If you're arriving here from broader headless-browser research, the overview of what "browserless Chromium" actually means is a useful companion read before you start integrating.

Here's how the pattern looks in a real request to Browsevra: Authorization: Bearer YOUR_BROWSEVRA_TOKEN. Full endpoint references and request formats are in the Docs, and plan limits tied to your authenticated usage are on the Pricing page. Head to browsevra to generate a token and send your first authenticated request.

Frequently Asked Questions

Do I need to write 'Bearer' with a capital B in the Authorization header?

Yes, by convention it should be capitalized as "Bearer" per RFC 6750, and many server implementations parse it case-sensitively. Sending "bearer" in lowercase can cause a silent 401 on strict implementations even though the token itself is valid. Stick to the documented casing exactly as shown in the API's reference.

Can I pass my API token as a URL query parameter instead of a header?

Technically some APIs allow it, but it's not recommended. Query parameters get logged by servers and proxies, stored in browser history, and can leak via the Referer header to other domains — none of which happens with a header sent over HTTPS. Use the Authorization header or a documented custom header instead.

What's the difference between a 401 and a 403 error when using an auth token?

A 401 means the server couldn't authenticate the request at all — the token is missing, malformed, or invalid. A 403 means authentication succeeded but the authenticated identity doesn't have permission for that specific action or resource. Fixing a 403 usually means adjusting permissions or plan access, not the token format.

Is an API key the same thing as a bearer token?

No. An API key typically identifies an application or project and is often long-lived, while a bearer token typically represents a user or session and usually expires. Both can travel in a header, but they represent different security models and shouldn't be treated as interchangeable.

How long should an API auth token be valid before it expires?

There's no universal rule — it depends on the API's security model and how the token is issued. Session-based bearer tokens often expire in minutes to hours and require refreshing, while project-level API keys are frequently long-lived until manually rotated. Always check the specific API's documentation for its expiry policy.

Can I use both an API key and a bearer token in the same request?

Yes, some APIs require both — for example, a bearer token to authenticate a user session and a separate API key to identify the calling application or project. When this is the case, the documentation will specify separate headers for each, such as Authorization for the bearer token and X-API-Key for the key.