Authentication

Two key types. Publishable keys live in your frontend. Secret keys live on your server. Both lock to the domains you allow-list in the console. Both rotate without dropping traffic.

Key types

Using a publishable key

Pass the publishable key as the key query param. The browser is the caller. Lock the key to your domains in Console → API Keys → Allowed domains so nobody else can hot-link your quota.

<img src="https://avtrz.dev/v1/avatar?key=pk_live_7f3e21bc94aa&linkedin_url=linkedin.com/in/alex-rivera&size=128" alt="" />

Using a secret key

For server-side fetches (populating a database column, prefetching a list, or wiring an agent), use a secret key via the x-api-key header. The endpoint still returns a 302; either follow it or hand the Location URL to your client.

const res = await fetch(
  "https://avtrz.dev/v1/avatar?linkedin_url=linkedin.com/in/alex-rivera&size=256",
  {
    headers: { "x-api-key": process.env.AVTRZ_SECRET! },
    redirect: "manual",
  }
);
// 302 with Location → CDN URL. Either follow it or pass it to the browser.
const cdnUrl = res.headers.get("location");

Rotating keys safely

Keys are independent: creating a new one doesn't affect the old one. Roll deploys at your own pace, then revoke the old key when you're done. There is no maintenance window.

1. Create a new key of the same type. The old one keeps working.
2. Deploy the new key to your environments. Watch the usage chart switch over.
3. Revoke the old key once 100% of traffic is on the new one.

Authentication errors

Auth errors return 401 on the JSON body. The image endpoint serves an SVG fallback so a broken key never breaks your UI.