Skip to main content
Logo

Authentication

Request an OpenAPI key and pass tokens with each request.

Two identity types

The OpenAPI accepts two identities:

Identity How to get it When to use
OpenAPI Key (recommended) Self-serve under Settings → OpenAPI Server-side calls, CLI, long-running agent integrations
Logged-in session cookie Held automatically once signed in Same-site web frontend

OpenAPI Keys are the standard for external integrations. One account can hold multiple keys, each independently named, scope-limited, and revocable.

Create an OpenAPI Key

  1. Sign in at bestblogs.dev
  2. Open Settings → OpenAPI → "Create new key"
  3. Name the key (e.g. "My agent," "Notion integration")
  4. Pick scopes (default read:public; check write:capture if you need to write bookmarks / highlights)
  5. Copy the generated key (shown only once) and store it safely

Request format

All OpenAPI requests need an HTTP header:

Authorization: Bearer <YOUR_OPENAPI_KEY>

Example (curl):

curl https://bestblogs.dev/api/v2/resources?limit=10 \
  -H "Authorization: Bearer bb_live_xxxxxxxxxxxx"

Quotas & rate limits

Endpoint family Rate limit
Discover 60 req/min (Free) / 600 req/min (Pro)
Read 30 / 300 req/min
Capture (writes) 30 / 300 req/min
AI Reading Assistant / Copilot Shares the in-app AI quota, token-metered

Hitting the limit returns 429 Too Many Requests with a Retry-After header (seconds).

Security recommendations

  • Never put it in the frontend: an OpenAPI Key is a password — don't ship it in web frontend code or open-source repos.
  • Use environment variables: load via BESTBLOGS_API_KEY on servers or CLIs.
  • Minimum scope: enable only the write permissions you actually need.
  • Rotate regularly: if you suspect a leak, revoke and recreate immediately under Settings → OpenAPI.

Error codes

Status Meaning
401 Unauthorized Key missing or invalid
403 Forbidden Key is valid but its scope doesn't allow the endpoint (e.g. using read:public for a write endpoint)
404 Not Found Resource doesn't exist or isn't visible to you
429 Too Many Requests Rate-limited; wait per Retry-After
5xx Transient server error; safe to retry with exponential backoff
← Back to docs home