OAuth Token Refresh Recovery
Keep connections alive when short-lived provider tokens expire.
What it adds
A refresh lifecycle that renews access tokens safely under concurrency and stops cleanly when renewal is impossible.
What your agent is told to do
6
What your agent is told to do
6-
1
Refresh proactively, shortly before expiry, rather than waiting for a 401. Also handle the 401 path — provider clocks and your clock disagree.
-
2
Serialize refresh per connection with a lock. Concurrent refreshes race, and with rotating refresh tokens the loser's token is already dead — the whole connection dies with it.
-
3
Write the new access token and any replacement refresh token in one atomic update. A crash between the two leaves the connection unrecoverable.
-
4
Classify refresh failures. A network error or 5xx is retryable with backoff; invalid_grant is permanent. Do NOT retry a permanent failure — it burns quota and never succeeds.
-
5
Notify the user only when a human must reauthorize. A transient refresh failure that self-heals must produce no notification at all.
-
6
The status surface and the reconnect button are owned by Integration Connection Health; set the state and let that feature render it.
Edge cases it handles
6
Edge cases it handles
6- Some providers rotate the refresh token on every use and some do not. Handle both; assuming the wrong one silently breaks connections after the first refresh.
- A request that was in flight when the token expired must be retried once with the new token, not dropped.
- Background jobs and web requests may both hit expiry at once. The lock has to span processes, not just threads.
- A refresh token can expire from disuse. A dormant connection needs the same reauthorization path as a revoked one.
- Storing the new token must survive a failed write to the provider-facing side — never delete the old token until the replacement is committed.
- Repeated invalid_grant across many connections at once usually means a provider-side app change, not user error. Detect the pattern and alert operators before mass-emailing users.
Definition of done
8
Definition of done
8- Tokens are refreshed before expiry, and expired-token responses are also handled.
- Concurrent refresh attempts for one connection are serialized and only one call reaches the provider.
- Access and rotating refresh tokens are persisted atomically.
- invalid_grant halts retries immediately; transient errors back off and retry.
- Users are notified only when reauthorization is genuinely required.
- A crash mid-refresh leaves the connection either on the old token or the new one, never on neither.
- The feature matches the existing design system.
- No existing functionality is broken.
Related features
Contentful Entry Sync
Contentful Entry Sync
Create and update Contentful entries against the connected space, environment, and locale.
What it does
A sync that writes app records into Contentful entries using the connected space's content model and locale configuration.
How it works
- 1 Have the operator select the space, the environment, and the default locale during connection, and store all three, because writing production content into a sandbox environment is an easy and expensive mistake.
- 2 Fetch the content model at connection time and again before each sync run, map app fields to entry fields by their stable identifiers, and validate the value type against the model before attempting the write.
- 3 Write every localized field under an explicit locale rather than relying on whatever the space treats as default, and state clearly which locales the app owns and which it leaves to editors.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/contentful-entry-sync
Typesense Index Sync
Typesense Index Sync
Keep a search index in step with your records so results stay current and correctly scoped.
What it does
A one-way sync from the app's records into a Typesense collection, with server-enforced tenant filtering and a rebuild path.
How it works
- 1 Identify every model users search today and declare the indexed shape explicitly: the fields people type into, the fields they filter and sort on, and nothing more. Treat a missing or newly added field as absent rather than letting the document fail validation.
- 2 Reuse the app's existing background-job system to push creates, updates, and deletes. Do not index inside the request cycle; a slow or unreachable search service must never make a save fail or hang.
- 3 Build the tenant, workspace, and permission filter on the server at query time and attach it to every search. Do not accept a filter, collection name, or scope value from a client-supplied parameter, because anything the browser can set the browser can change.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/typesense-index-sync
Mapbox Geocoding
Mapbox Geocoding
Convert typed locations into coordinates and structured addresses the app can use.
What it does
Forward and reverse geocoding with confirmed matches, controlled result bias, and coordinate precision rules.
How it works
- 1 Separate the two directions explicitly: text to coordinates for entry and search, coordinates to address for a dropped pin or a device location. They take different inputs, carry different confidence, and fail differently.
- 2 Present ambiguous matches as a list the user confirms. Silently taking the first result is how a record ends up in the wrong country with nobody noticing for months.
- 3 Bias results toward a location only when the app genuinely knows one, such as a workspace address or the map viewport the user is already looking at.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/mapbox-geocoding
How it works
-
1
Copy the link
Grab the Markdown instruction URL for this feature.
-
2
Give it to your AI
Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
-
3
It inspects, then implements
Your agent reads your existing app first, then adds the feature to fit it.
Works with your stack
These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.
Need it tighter than that? Customize the feature and tell it exactly what you're running.