OAuth 2.0: what the docs don't say

Migrating an integration between APIs, I ran into a couple of details of the OAuth 2.0 flow that the documentation doesn’t make clear. Writing them down here, mostly for the future me who touches this again.

The refresh token doesn’t always come back

The first code-for-tokens exchange returns access_token and refresh_token. But on some later refreshes the refresh_token doesn’t come back, so if you overwrite the one you had with a null, you lose the ability to refresh. Rule: only update the refresh token if the new one is present.

Isolate the provider behind an interface

The architecture lesson: don’t let the domain model know which provider the data comes from. A common interface and one adapter per provider. The day you switch APIs, you touch one file, not the whole app.

Mental note: what’s a headache one day is blog content the next. Documenting the failure is worth more than hiding it.