Authentication

A first request — curl

The fastest sanity check. Replace $ARCHIVIST_KEY with the key we issued you:

curl https://api.archivist.dev/bills \
  -H "Authorization: Bearer $ARCHIVIST_KEY" \
  -H "Accept: application/json"

A 200 response with a populated items array means the key is good. A 401 means the header was missing or the key is wrong; a 403 means the key’s tier doesn’t have access to this endpoint.

From JavaScript

The fetch pattern is identical: set Authorization and call the endpoint. Use the built-in fetch — no SDK is required.

// Node 20+ (built-in fetch)
const res = await fetch('https://api.archivist.dev/bills', {
  headers: {
    Authorization: `Bearer ${process.env.ARCHIVIST_KEY}`,
    Accept: 'application/json',
  },
});
if (!res.ok) throw new Error(`Archivist ${res.status}`);
const { items, nextCursor } = await res.json();

In a browser, the key should never reach the client. Pass the user’s session through your own backend and proxy the request.

// Browser-side fetch — load the key through your backend, never expose it.
const res = await fetch('/api/proxy/bills', {
  headers: { Authorization: `Bearer ${userToken}` },
});
const data = await res.json();

Key placement — what to do (and what not to)

Errors & limits

Errors are JSON. Every error response carries a stable shape so clients can match on error without parsing prose:

{
  "error": "Rate limit exceeded"
}