Storing and refreshing social media OAuth tokens securely

Where and how should you store OAuth tokens?

How long do access tokens last? Platform table

Per official docs as of 2026-09-17. Always compute expiry from expires_in in the response — don't hard-code the numbers below.

yesnoScroll the table sideways

Refresh strategy: when and how to refresh tokens

1. 1

   Persist expiry

   On every refresh write expires_at and, if present, refresh_expires_at. Both are ready on TokenBundle.

2. 2

   Schedule by window

   For example, hourly: TikTok with under 4 hours left, Instagram Login with under 10 days left (token at least 24 hours old), LinkedIn with a refresh token and under 7 days left.

3. 3

   One token, one refresher

   Lock the row. TikTok and amoCRM rotate refresh tokens: if two workers refresh in parallel, the second fails with a stale token.

4. 4

   Write atomically

   Save the new access and refresh token in one transaction. If the write fails, the new refresh token is lost and the account disconnects.

5. 5

   Classify errors

   AuthError — set status reauth_required and send the user a reconnect link. RateLimitError or TransportError — retry later.

6. 6

   Warn early where there's no refresh

   For Facebook user tokens or LinkedIn without refresh tokens, prompt the user to reconnect 7–14 days before expiry.

Refresh worker (Socialift SDK)

One client per provider is enough: the token is passed to every method and never stored on the client.

from socialift import ApiError, AuthError, Instagram, LinkedIn, RateLimitError, TikTok

async def refresh_row(row, tt: TikTok, ig: Instagram, li: LinkedIn) -> None:
    try:
        if row.provider == "tiktok":
            bundle = await tt.refresh_token(decrypt(row.refresh_token_enc))
        elif row.provider == "instagram":
            bundle = await ig.refresh_token(decrypt(row.access_token_enc))
        else:
            bundle = await li.refresh(decrypt(row.refresh_token_enc))
    except RateLimitError:
        raise  # retry later
    except ApiError as exc:
        if not isinstance(exc, AuthError) and exc.status != 400:
            raise
        await db.set_status(row.id, "reauth_required")
        return
    await db.save_bundle(  # one transaction
        row.id,
        access_token_enc=encrypt(bundle.access_token),
        refresh_token_enc=encrypt(bundle.refresh_token) if bundle.refresh_token else None,
        expires_at=bundle.expires_at,
    )

Encrypting tokens at rest: Fernet and key rotation

cryptography is already an SDK dependency. Fernet provides authenticated encryption (AES-128-CBC + HMAC-SHA256); MultiFernet enables key rotation.

import os
from cryptography.fernet import Fernet, MultiFernet

# TOKEN_KEYS="new_key,old_key" — the first key encrypts
_keys = MultiFernet([Fernet(k) for k in os.environ["TOKEN_KEYS"].split(",")])

def encrypt(token: str) -> bytes:
    return _keys.encrypt(token.encode())

def decrypt(blob: bytes) -> str:
    return _keys.decrypt(blob).decode()

def reencrypt(blob: bytes) -> bytes:
    """Background migration after a key change: re-encrypts under the new key."""
    return _keys.rotate(blob)

How should a multi-tenant token table look?

App secrets, client secrets and encryption keys never go in this table — they belong in a secret manager or environment variables.

What is appsecret_proof and why use it?

How do you detect a revoked token?

Least-privilege scopes and secret management

• ▸Request only the scopes a feature needs — App Review and audits check exactly that.
• ▸Users can decline some permissions — store what was actually granted: fb.granted_scopes(token), li.introspect(token) on LinkedIn.
• ▸Separate apps and keys per environment (dev, staging, prod); production tokens never land in a dev database.
• ▸Plan app secret rotation ahead: appsecret_proof and webhook signature checks depend on it — update every service together.
• ▸Keep tokens out of logs, Sentry and analytics; mask them in error messages too.
• ▸Encrypt the Telegram account session string (export_session()) exactly like a token.
• ▸Rotate the encryption key at least yearly and when staff leave (MultiFernet or KMS).
• ▸Surface accounts that need reconnecting in your UI — a silent disconnect is the most expensive failure.