Scopes in practice

Scopes let a key say what it is allowed to do. They are optional, and for a lot of integrations they are genuinely unnecessary. It is worth being honest about which case you are in rather than adopting them because they sound responsible.

When they do nothing for you

One key, one endpoint, one caller. There is nothing to separate. A scope check that always passes is not security, it is paperwork — and paperwork that always passes trains people to ignore it.

When they start to matter

The moment two callers share an account and should not share capability.

• An agency with a key per client, where one client's key should never reach another's data.
• A mobile app and an admin panel on the same account.
• A CI pipeline that should be able to read and never write.
• A partner integration you want to grant narrowly and revoke cleanly.

The question to ask is: *if this key leaked, what could someone do with it that I would mind?* Scopes are how you shrink that answer.

The migration trap

Here is the practical advice, and it is the only part of this article that will save you time.

Send the scope parameter from day one, even when the key holds every scope and the check always passes. It costs nothing and it is a no-op.

Because the painful part of adopting scopes later is not configuring them — that is a few clicks. It is going through a codebase you have not touched in a year, finding every call site, and working out what each one should be allowed to do. Half of them you will not remember writing. That is the project, and it does not exist if the parameter is already there.

A note on the empty set

A key with no scopes selected has full access, not zero access.

That trips people up, and it is worth stating plainly: it means "unscoped", not "permitted nothing". The alternative would have broken every existing integration the moment the feature shipped, which is not a trade we were willing to make.

If you want a key that can do nothing, revoke it.