fix(instagram): proactively refresh long-lived tokens before expiry

Meta only allows refreshing still-valid Instagram tokens, so refresh within 14 days of expiry (after the 24h age gate) instead of waiting until after accessTokenExpiresAt.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

apps/sim/app/api/auth/oauth/utils.ts

@@ -8,6 +8,7 @@ import { withLeaderLock } from '@/lib/concurrency/leader-lock'
 import { coalesceLocally } from '@/lib/concurrency/singleflight'
 import { decryptSecret } from '@/lib/core/security/encryption'
 import { refreshOAuthToken } from '@/lib/oauth'
+import { isInstagramProvider, shouldProactivelyRefreshInstagramToken } from '@/lib/oauth/instagram'
 import {
   getMicrosoftRefreshTokenExpiry,
   isMicrosoftProvider,
@@ -450,6 +451,7 @@ export async function getOAuthToken(userId: string, providerId: string): Promise
       accessTokenExpiresAt: account.accessTokenExpiresAt,
       idToken: account.idToken,
       scope: account.scope,
+      updatedAt: account.updatedAt,
     })
     .from(account)
     .where(and(eq(account.userId, userId), eq(account.providerId, providerId)))
@@ -463,19 +465,33 @@ export async function getOAuthToken(userId: string, providerId: string): Promise
 
   const credential = connections[0]
 
-  // Determine whether we should refresh: missing token OR expired token
+  // Determine whether we should refresh: missing/expired token, or Instagram
+  // long-lived token nearing expiry (Meta cannot refresh after expiry).
   const now = new Date()
   const tokenExpiry = credential.accessTokenExpiresAt
-  const shouldAttemptRefresh =
+  const accessTokenNeedsRefresh =
     !!credential.refreshToken && (!credential.accessToken || (tokenExpiry && tokenExpiry < now))
+  const instagramNeedsProactiveRefresh =
+    !!credential.refreshToken &&
+    isInstagramProvider(providerId) &&
+    shouldProactivelyRefreshInstagramToken({
+      accessTokenExpiresAt: credential.accessTokenExpiresAt,
+      updatedAt: credential.updatedAt,
+      now,
+    })
 
-  if (shouldAttemptRefresh) {
-    return performCoalescedRefresh({
+  if (accessTokenNeedsRefresh || instagramNeedsProactiveRefresh) {
+    const fresh = await performCoalescedRefresh({
       accountId: credential.id,
       providerId,
       refreshToken: credential.refreshToken!,
       userId,
     })
+    if (fresh) return fresh
+    if (!accessTokenNeedsRefresh && credential.accessToken) {
+      return credential.accessToken
+    }
+    return null
   }
 
   if (!credential.accessToken) {
@@ -550,7 +566,18 @@ export async function refreshAccessTokenIfNeeded(
     refreshTokenExpiresAt &&
     refreshTokenExpiresAt <= proactiveRefreshThreshold
 
-  const shouldRefresh = accessTokenNeedsRefresh || refreshTokenNeedsProactiveRefresh
+  // Instagram long-lived tokens can only be refreshed while still valid.
+  const instagramNeedsProactiveRefresh =
+    !!credential.refreshToken &&
+    isInstagramProvider(credential.providerId) &&
+    shouldProactivelyRefreshInstagramToken({
+      accessTokenExpiresAt,
+      updatedAt: credential.updatedAt,
+      now,
+    })
+
+  const shouldRefresh =
+    accessTokenNeedsRefresh || refreshTokenNeedsProactiveRefresh || instagramNeedsProactiveRefresh
 
   const accessToken = credential.accessToken
 
@@ -567,8 +594,8 @@ export async function refreshAccessTokenIfNeeded(
     })
     if (fresh) return fresh
 
-    // If refresh was only triggered proactively (Microsoft refresh-token aging),
-    // the still-valid access token is a fine fallback.
+    // If refresh was only triggered proactively (Microsoft refresh-token aging /
+    // Instagram long-lived nearing expiry), the still-valid access token is fine.
     if (!accessTokenNeedsRefresh && accessToken) {
       logger.info(`[${requestId}] Refresh unavailable; reusing still-valid access token`)
       return accessToken
@@ -616,7 +643,18 @@ export async function refreshTokenIfNeeded(
     refreshTokenExpiresAt &&
     refreshTokenExpiresAt <= proactiveRefreshThreshold
 
-  const shouldRefresh = accessTokenNeedsRefresh || refreshTokenNeedsProactiveRefresh
+  // Instagram long-lived tokens can only be refreshed while still valid.
+  const instagramNeedsProactiveRefresh =
+    !!credential.refreshToken &&
+    isInstagramProvider(credential.providerId) &&
+    shouldProactivelyRefreshInstagramToken({
+      accessTokenExpiresAt,
+      updatedAt: credential.updatedAt,
+      now,
+    })
+
+  const shouldRefresh =
+    accessTokenNeedsRefresh || refreshTokenNeedsProactiveRefresh || instagramNeedsProactiveRefresh
 
   // If token appears valid and present, return it directly
   if (!shouldRefresh) {

apps/sim/lib/oauth/index.ts

@@ -1,3 +1,4 @@
+export * from './instagram'
 export * from './microsoft'
 export * from './oauth'
 export * from './types'

apps/sim/lib/oauth/instagram.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import {
+  INSTAGRAM_MIN_TOKEN_AGE_MS,
+  INSTAGRAM_PROACTIVE_REFRESH_THRESHOLD_DAYS,
+  isInstagramProvider,
+  shouldProactivelyRefreshInstagramToken,
+} from '@/lib/oauth/instagram'
+
+describe('instagram oauth helpers', () => {
+  it('identifies the instagram provider', () => {
+    expect(isInstagramProvider('instagram')).toBe(true)
+    expect(isInstagramProvider('facebook')).toBe(false)
+  })
+
+  it('does not refresh when the token is already expired', () => {
+    const now = new Date('2026-07-11T12:00:00.000Z')
+    expect(
+      shouldProactivelyRefreshInstagramToken({
+        accessTokenExpiresAt: new Date(now.getTime() - 60_000),
+        updatedAt: new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000),
+        now,
+      })
+    ).toBe(false)
+  })
+
+  it('does not refresh tokens younger than 24 hours', () => {
+    const now = new Date('2026-07-11T12:00:00.000Z')
+    expect(
+      shouldProactivelyRefreshInstagramToken({
+        accessTokenExpiresAt: new Date(now.getTime() + 2 * 24 * 60 * 60 * 1000),
+        updatedAt: new Date(now.getTime() - INSTAGRAM_MIN_TOKEN_AGE_MS + 60_000),
+        now,
+      })
+    ).toBe(false)
+  })
+
+  it('refreshes when expiry is within the proactive window and the token is old enough', () => {
+    const now = new Date('2026-07-11T12:00:00.000Z')
+    expect(
+      shouldProactivelyRefreshInstagramToken({
+        accessTokenExpiresAt: new Date(
+          now.getTime() + (INSTAGRAM_PROACTIVE_REFRESH_THRESHOLD_DAYS - 1) * 24 * 60 * 60 * 1000
+        ),
+        updatedAt: new Date(now.getTime() - INSTAGRAM_MIN_TOKEN_AGE_MS - 60_000),
+        now,
+      })
+    ).toBe(true)
+  })
+
+  it('does not refresh when plenty of lifetime remains', () => {
+    const now = new Date('2026-07-11T12:00:00.000Z')
+    expect(
+      shouldProactivelyRefreshInstagramToken({
+        accessTokenExpiresAt: new Date(
+          now.getTime() + (INSTAGRAM_PROACTIVE_REFRESH_THRESHOLD_DAYS + 5) * 24 * 60 * 60 * 1000
+        ),
+        updatedAt: new Date(now.getTime() - 40 * 24 * 60 * 60 * 1000),
+        now,
+      })
+    ).toBe(false)
+  })
+})

apps/sim/lib/oauth/instagram.ts

@@ -0,0 +1,38 @@
+/** Refresh while the long-lived token still has this many days left. */
+export const INSTAGRAM_PROACTIVE_REFRESH_THRESHOLD_DAYS = 14
+
+/**
+ * Meta rejects refresh until the long-lived token is at least 24 hours old.
+ * @see https://developers.facebook.com/docs/instagram-platform/reference/refresh_access_token/
+ */
+export const INSTAGRAM_MIN_TOKEN_AGE_MS = 24 * 60 * 60 * 1000
+
+export function isInstagramProvider(providerId: string): boolean {
+  return providerId === 'instagram'
+}
+
+/**
+ * Whether an Instagram long-lived token should be refreshed before it expires.
+ * Meta cannot refresh expired tokens, so we must refresh while still valid.
+ */
+export function shouldProactivelyRefreshInstagramToken(options: {
+  accessTokenExpiresAt?: Date | null
+  updatedAt?: Date | null
+  now?: Date
+}): boolean {
+  const now = options.now ?? new Date()
+  const expiresAt = options.accessTokenExpiresAt
+  if (!expiresAt || expiresAt <= now) {
+    return false
+  }
+
+  const updatedAt = options.updatedAt
+  if (updatedAt && now.getTime() - updatedAt.getTime() < INSTAGRAM_MIN_TOKEN_AGE_MS) {
+    return false
+  }
+
+  const proactiveThreshold = new Date(
+    now.getTime() + INSTAGRAM_PROACTIVE_REFRESH_THRESHOLD_DAYS * 24 * 60 * 60 * 1000
+  )
+  return expiresAt <= proactiveThreshold
+}