What my own API key couldn't tell me

After rotating an API key last week, I ran into something that felt embarrassing at first. Then I realized it wasn't my fault at all.

The key was fresh. The integration was already wired up. All I needed to know was: what is this key actually allowed to do? Simple question. Turns out, there was no simple answer.

There Was No "Ask the Key" Endpoint

The API had solid documentation. A clear list of tools. Descriptions, parameters, example responses. Everything you'd want from a public-facing reference.

What it didn't have was any way to ask: given this specific credential, which of these tools can I actually call?

So I did what you do when there's no good option. I started calling tools one at a time and reading the errors back. Permission denied. Permission denied. OK, that one worked. Permission denied.

It's exactly as tedious as it sounds. I was essentially binary-searching my own access level through trial and error, treating error responses as a discovery mechanism because no actual discovery mechanism existed. Like reading a restaurant menu by ordering dishes and waiting to see which ones the kitchen sends back.

Why This Happens So Often

Here's the thing: this isn't a documentation problem. The API was well-documented. The gap is something different.

Most API reference docs describe what the API can do. They are written from the perspective of the product. They tell you every available endpoint, every supported operation, every possible response code.

What they almost never tell you is what your key can do. That's a different question entirely, and it lives in a different layer. Scopes get assigned at key creation, or per environment, or by an admin in a dashboard somewhere. The reference docs don't know about that. The docs describe the catalog. Your credential is a subset of that catalog — a library card that doesn't tell you which shelves you're actually allowed to browse. And there's usually nothing sitting in between to bridge the two.

I've hit this before with other APIs, in other integrations, and every time the result is the same:

• You rotate a key
• You're not 100% sure what scope was applied when the new one was generated
• You'd rather not just assume it matches the old one
• You end up poking around manually to verify

That manual verification step is what kills you. Not because it takes forever, but because it's not reliable. You only discover what's broken when you call the thing that's broken. You don't get a clean picture. You get a scattered set of yes/no signals across whatever subset of tools you happened to test.

What the Fix Actually Looks Like

The pattern that solves this is straightforward. It just requires someone to build it.

Call it whoami, call it /auth/capabilities, call it whatever. The point is a single endpoint that takes the calling credential and returns what that credential is authorized to do. Not what the API supports in general. Not a copy of the docs. The actual granted scopes, specific to the key making the request.

From there you can diff it against the tool catalog. You can see at a glance what's covered and what isn't. You can catch a misconfigured key before it causes a silent failure somewhere in production. You can rotate with confidence because you can verify after rotating.

That's it. That's the whole thing.

The implementation doesn't have to be complicated. An array of granted scope strings is enough. The value isn't in rich metadata. The value is just in having a ground truth you can actually query, rather than inferring it from error responses.

The Broader Problem Is One of Perspective

API designers think about their API from the inside. They know what it does. They document what it does. That makes sense.

But the person integrating with it shows up from the outside, holding a credential, trying to figure out what they're allowed to do with it. Those are two very different starting points. Good discovery endpoints are designed for the second perspective, not the first.

A whoami-style capabilities endpoint is one of those small features that looks optional until you're the one staring at a fresh API key, watching permission-denied errors stack up, and realizing you're debugging something that should never have required debugging in the first place. I once spent the better part of an afternoon doing exactly that — methodically poking at endpoint after endpoint, each denial arriving like a polite but firm bouncer, until I finally mapped the boundaries of what I was allowed to touch. By the time I finished, I had a complete picture and a strong opinion about gaps in API design.

Build the endpoint. Make it queryable by the calling credential. Return the scopes. Those are the asks.