How I Explain 'Bring Your Own API Key' So It Doesn't Scare Buyers Off

Every one of my Obsidian plugins runs on the buyer’s own AI key. There’s no server of mine in the middle, no subscription, no account to create. That’s a genuinely good setup for the buyer once it’s running: their data goes straight to whichever AI provider they choose, and I never see any of it. But “once it’s running” is doing a lot of work in that sentence, because getting an API key set up is the one step in the whole install process that has nothing to do with my plugin at all, and it’s exactly where a buyer who’s never done it before can quietly give up.

I didn’t take this seriously enough in my first install guides. I wrote one line — “paste your API key into the settings” — and assumed that was self-explanatory. It isn’t, if you’ve never had a reason to visit an AI provider’s website before.

Say the honest sentence first, not last

The line I now open every setup guide with is the same one I’d want to read as a buyer: no server, no account, no telemetry, and your data only goes to the AI provider you configure yourself. That’s not a marketing line, it’s an accurate description of what BYOK actually means, and I say it before I ask the buyer to do anything. A buyer who understands why they’re being asked for a key is a lot more patient with the three or four steps it takes to get one than a buyer who’s just been told “paste key here” with no context.

Screenshots for the step that isn’t mine

The plugin’s own settings screen is easy to document, because I control it and I already know exactly what it looks like. The part I used to skip was the part before that: creating an account on the AI provider’s site and generating the key itself. That page belongs to someone else, changes its layout without warning me, and looks completely unfamiliar to someone who’s never had a reason to be there. I now screenshot that exact page — where the “create new key” button actually is, what the key looks like once it’s generated, the one warning box that matters (copy it now, you won’t see it again) — instead of describing it in a sentence and assuming the buyer will recognize the same layout I’m looking at.

Naming the cost instead of leaving it vague

BYOK means the buyer is paying the AI provider directly, usage-based, separate from whatever they paid me. If I don’t say that plainly, a buyer can read “bring your own key” as a technicality and be surprised later that using the plugin costs anything at all beyond the one-time purchase. I’d rather say it upfront and undersell the plugin a little than have someone feel like the real cost was hidden in the fine print. I don’t quote a specific number in the guide, because usage cost depends on how much someone actually runs the plugin and which model they pick, and a made-up figure would be worse than none. What I do say is the shape of it: small, ongoing, tied to actual use, and entirely outside my own product’s price.

Where the guide still fails

The honest gap I haven’t closed yet is what happens when a key doesn’t work. Wrong key format, a provider account that needs billing enabled before it’ll issue keys at all, a copy-paste that grabbed a trailing space — each of these produces a different, unhelpful error inside Obsidian, and my current guides don’t cover any of them individually. Right now the fallback is just “email me,” which works, but it means the guide is only doing half its job. The same discipline I wrote about for packaging n8n workflows applies here too: test it blind, pretending to be someone who’s never seen the setup before, and the failure cases are exactly what that kind of testing is supposed to surface. I haven’t done a proper blind pass on the key-setup step specifically, and it shows in the support emails I still get.

What actually changed

None of this required touching the plugin code. Every improvement so far has been in the guide: the order things are explained in, screenshots for the part I don’t control, and saying the cost out loud instead of leaving it implied. It’s the same lesson from the plugins I wrote about triaging a video backlog with — the tool doing the actual work is often the smaller half of the product. The other half is making sure a stranger who’s never seen any of it before can get from “I bought this” to “it’s running” without emailing me in between.