Skip to content
Markdown Viewer

Security

Markdown API authentication

Every request to the Markdown Viewer API is authenticated with a Bearer token. This page covers how to mint, format, rotate, and revoke API keys — and how to keep them out of client-side code in production.

The Authorization header

Pass your key in the standard Authorization header on every request:

Authorization: Bearer mdv_live_K8x_pP7iN1c4ZQ3oR2tA9vBh

API keys are stored as salted SHA-256 hashes on our side — we never see the raw value after creation. Treat them like passwords: store in a secrets manager, never log them, and rotate when in doubt.

Code examples

The same Bearer header works from any HTTP client. Use environment variables — never hard-code keys.

curl

curl -X POST 'https://trymarkdownviewer.com/api/v1/render' \
  -H "Authorization: Bearer $MDV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello"}'

JavaScript / Node

const res = await fetch("https://trymarkdownviewer.com/api/v1/render", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MDV_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ markdown: "# Hello" }),
});

Python

import os, requests

response = requests.post(
    "https://trymarkdownviewer.com/api/v1/render",
    headers={
        "Authorization": f"Bearer {os.environ['MDV_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"markdown": "# Hello"},
)
response.raise_for_status()

Key formats & prefixes

  • mdv_live_* — production keys minted on our hosted site.
  • mdv_test_* — issued by local or self-hosted dev environments.

The first 12 characters of every key are the visible prefix shown in your dashboard — they let you identify which key you're looking at without revealing the secret. The remaining ~24 characters are the actual entropy.

Rotation & revocation

From the dashboard you can revoke a key (immediate, irreversible) or regenerate it — which atomically revokes the old key and mints a new one with the same label. Requests using the old key start returning HTTP 401 with error code unauthorized within seconds.

Recommended rotation triggers

  • Suspected leak (accidentally pushed to a public repo, shared in chat, etc.)
  • Teammate with key access leaves the team
  • Quarterly hygiene rotation for production keys
  • Migration between environments (staging → prod cutover)

Security best practices

Do
  • Store keys in a secrets manager (Vault, AWS Secrets Manager, Netlify env vars).
  • Use a separate key per environment so you can revoke them independently.
  • Set up alerting on HTTP 401 responses to catch revoked or rotated keys.
  • Limit which services can read the secret via least-privilege IAM.
  • Log who accessed which key from the dashboard's audit trail.
Don't
  • Hard-code keys in source files — they end up in git history forever.
  • Embed keys in client-side JavaScript or mobile app binaries.
  • Share one key across environments — revocation becomes painful.
  • Email or DM keys; share them via your secrets manager instead.
  • Log the full key on errors — only ever log the visible prefix.

Authentication failures

Authentication failures always return HTTP 401 with error.code = "unauthorized":

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

Common causes: missing header, typo in Bearer prefix, revoked key, copy-paste truncation, or a key from a different environment. See the unauthorized error for full remediation steps.

Authentication FAQ

How do I authenticate with the Markdown Viewer API?
Send an `Authorization: Bearer <YOUR_API_KEY>` header with every request. The key is created from the API Keys page in your dashboard. There are no other auth schemes — no OAuth, no signed requests, no basic auth.
Can I recover a lost API key?
No. API keys are stored as salted SHA-256 hashes on our side. If you lose a key, revoke it (or regenerate it from the dashboard) and create a new one. The new key takes effect immediately.
How often should I rotate API keys?
At minimum, rotate after any suspected leak or when a teammate with access leaves. Many teams also rotate keys on a quarterly schedule as a hygiene measure. Use the dashboard's regenerate button — it atomically revokes the old key and mints a replacement with the same label.
Is it safe to call the API from the browser?
No — never put API keys in client-side code. They'd be visible in your bundle and to anyone using DevTools. Instead, call your own backend, validate the user, and forward the request server-side with the API key attached.
What's the difference between mdv_live_ and mdv_test_ keys?
mdv_live_ keys are production keys issued by the hosted Markdown Viewer service. mdv_test_ keys are issued by local or self-hosted environments. Both follow the same format and are passed identically in the Authorization header.
How many API keys can I create?
Free accounts can keep one active key at a time. Paid plans allow up to 25 active keys per account so you can give each environment (production, staging, CI, local) its own.