Token Refresh

Authpipe keeps OAuth tokens fresh through three mechanisms: background scheduling, on-demand refresh, and auto-refresh on getCredential.

Background refresh

A scheduler runs continuously, querying for connections and installations with tokens expiring soon. It refreshes tokens before they expire using the stored refresh_token and the provider config’s client_secret.

• Tokens are refreshed before expiry (with a buffer window)
• The new access_token and refresh_token are encrypted and stored
• A connection.refreshed event is emitted on success

Auto-refresh on getCredential

When you call getCredential, Authpipe checks if the token is expired or about to expire. If so, it refreshes the token inline before returning it. This means you always get a valid token without any extra work.

The SDK also caches credentials locally (default 5-minute TTL) with awareness of token expiry — cached entries are evicted if the token’s expires_at minus a 5-minute buffer has passed.

On-demand refresh

Force an immediate token refresh for a specific connection.

Node

const result = await authpipe.refreshConnection("conn_abc123");

console.log(result.refreshed);  // true
console.log(result.expires_at); // new expiry timestamp

Go

result, err := client.RefreshConnection(ctx, "conn_abc123")
// result.Refreshed, result.ExpiresAt

Python

result = client.refresh_connection(connection_id="conn_abc123")
# result.refreshed, result.expires_at

When refresh fails

If a token refresh fails (provider rejected the refresh token, refresh token expired, etc.):

1. The connection status is set to needs_reauth
2. A connection.failed event is emitted
3. A connection.reauth_required event is emitted
4. Both events are delivered to your webhook URL if configured

The user must re-authorize to restore the connection. Create a new auth session and redirect them through the OAuth flow again.

Connection statuses

Status	Meaning
active	Token is valid and working
needs_reauth	Token refresh failed; user must re-authorize
failed	Health check or refresh failed repeatedly
revoked	Connection was explicitly disconnected

Client-side caching

All SDKs cache credentials locally to reduce API calls.

SDK	Default TTL	Disable
Node	300s (5min)	cache: false
Go	5min	authpipe.WithoutCache()
Python	300s (5min)	cache=False

The cache respects token expiry. If a token’s expires_at is within 5 minutes, the cached entry is evicted and a fresh token is fetched.

Node

// Custom cache TTL
const authpipe = new Authpipe({
  apiKey: "sk_...",
  cacheTtlSeconds: 60, // 1 minute
});

// Disable caching
const authpipe = new Authpipe({
  apiKey: "sk_...",
  cache: false,
});

Go

// Custom cache TTL
client := authpipe.NewClient("sk_...", authpipe.WithCache(time.Minute))

// Disable caching
client := authpipe.NewClient("sk_...", authpipe.WithoutCache())

Python

# Custom cache TTL
client = Authpipe(api_key="sk_...", cache_ttl_seconds=60)

# Disable caching
client = Authpipe(api_key="sk_...", cache=False)

Client secret rotation

When you rotate a provider config’s client_secret (via updateProviderConfig), existing tokens remain valid. The next refresh uses the new secret. No connections are invalidated.

However, changing the client_id invalidates all downstream tokens — all installations and connections are marked needs_reauth.