Overview
This document details the OAuth and authentication token lifecycle for each social and advertising platform connector supported by Claravine. It covers access token expiration windows, token renewal mechanisms, renewal credential lifetimes, when full user re-authorization is required, and the events that trigger re-authorization — all sourced directly from each platform's official developer documentation.
Keeping integrations authorized is critical for uninterrupted data synchronization between Claravine's Data Standards Cloud and connected ad platforms. Token expiration or revocation will halt inbound and outbound data syncs and may delay campaign operations. Administrators should establish proactive monitoring and re-authorization workflows based on each platform's specific requirements.
Important: This document reflects each platform's official developer documentation as of the date above. Token behavior, expiration rules, and re-authorization requirements are subject to change at any time by the respective platform. All 'no fixed expiration' references indicate the absence of a scheduled time-based expiry — not a guarantee of permanent access. See the Footnotes & Disclaimers section for full clarifications.
Connector Credential Summary
The table below provides a consolidated view of token lifetimes and re-authorization requirements across supported social and ad platform connectors. See the Detailed Platform Requirements section and Footnotes for full context and disclaimers.
| Platform | Access Token Lifetime | Token Renewal Mechanism | Renewal Credential Lifetime | Re-Auth Requirement | Auth Method |
|---|---|---|---|---|---|
| Meta Ads Manager | Short-lived: ~1–2 hoursLong-lived: ~60 days | Token extension or re-issuance (Meta does not implement a standard OAuth refresh token) | No fixed expiration for some System User tokens; otherwise ~60 days depending on token type | Required if token expires, is revoked, or permissions change | OAuth 2.0 |
| LinkedIn Ads | 60 days (expires_in: 5,184,000 sec) | OAuth 2.0 refresh token | Up to 1 year (refresh_token_expires_in: ~525,600 min / 31,536,000 sec) | Required when refresh token expires (~1 year) or is revoked | OAuth 2.0 |
| TikTok Ads (Business API) | 24 hours (86,400 sec) | OAuth 2.0 refresh token | Up to 1 year (31,536,000 sec); requires active daily refresh of the access token using the refresh token | Required when refresh token expires (~1 year) or is revoked | OAuth 2.0 |
| Google Ads | ~1 hour (3,600 sec) | OAuth 2.0 refresh token | No fixed expiration in production apps*; 7 days in testing/unverified app status | Rarely required. Required if: token is revoked, user removes app access, the 100-token-per-account limit is exceeded, or the app remains in 'Testing' status | OAuth 2.0 |
| Google Campaign Manager 360 (CM360) | ~1 hour (3,600 sec) | OAuth 2.0 refresh token or Service Account key (automatic, no user interaction) | No fixed expiration in production apps*; 7 days in testing mode. Service account keys do not expire unless rotated or revoked. | Not required for service accounts. For user OAuth: same conditions as Google Ads. | OAuth 2.0 or Service Account |
| Google Display & Video 360 (DV360) | ~1 hour (3,600 sec) | OAuth 2.0 refresh token or Service Account key (automatic, no user interaction) | No fixed expiration in production apps*; 7 days in testing mode. | Not required for service accounts. For user OAuth: same conditions as Google Ads. | OAuth 2.0 or Service Account |
| Snapchat Ads | ~1 hour (3,600 sec) | OAuth 2.0 refresh token | Not explicitly defined in public documentation; generally long-lived unless revoked. Implementations should treat refresh tokens as revocable at any time. | Required if the refresh token becomes invalid or is revoked | OAuth 2.0 |
| Pinterest Ads Manager | Up to 30 days (2,592,000 sec) for the continuous refresh model | OAuth 2.0 refresh token (continuous/rolling model) | 60-day rolling window, reset upon each successful refresh. Legacy 365-day non-rolling refresh tokens are no longer supported. | Required if the refresh token is not refreshed within its 60-day rolling window, or if it is revoked | OAuth 2.0 |
| Amazon Ads (Login with Amazon) | ~1 hour (3,600 sec) | OAuth 2.0 refresh token (LWA) | No fixed expiration for standard Ads API integrations; subject to revocation. Note: Amazon Selling Partner API (SP-API) integrations have a distinct 365-day annual re-authorization requirement — this does not apply to the standard Amazon Ads API. | Required if the LWA refresh token is revoked or authorization is removed by the account holder | Login with Amazon |
| The Trade Desk | ~24 hours for short-lived tokens | Proprietary credential exchange (POST to /v3/authentication) or Long-Lived API Token (generated in TTD UI) | Long-Lived API Tokens: no fixed expiration unless revoked. Short-lived tokens require re-authentication every ~24 hours. | Not required for Long-Lived API Tokens (unless revoked). Required approximately every 24 hours when using short-lived credential-exchange tokens. | Proprietary Token Authentication |
* 'No fixed expiration' = no scheduled time-based expiry. Subject to revocation. Not a guarantee of permanent access. See Footnotes & Disclaimers section.
Detailed Platform Requirements
The sections below provide full detail on each platform's authentication model, token cadence, trigger events for re-authorization, implementation notes, and links to source documentation.
1. Meta Ads Manager
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (Facebook Login) |
| Access Token Lifetime | Short-lived: ~1–2 hoursLong-lived: ~60 days |
| Token Renewal Mechanism | Token extension or re-issuance (Meta does not implement a standard OAuth refresh token) |
| Renewal Credential Lifetime | No fixed expiration for some System User tokens; otherwise ~60 days depending on token type |
| Re-Authorization Requirement | Required if token expires, is revoked, or permissions change |
| Trigger Events | Token expiry (long-lived: ~60 days), password change, permission scope change, user removed from Business Manager, security-driven revocation |
Implementation Notes
Meta does not implement OAuth refresh tokens in the standard sense. Long-lived tokens are extended or re-issued via the token exchange endpoint. System User tokens issued under Marketing API Standard Access may not expire automatically, but this is not universally guaranteed and remains subject to revocation.
Claravine connects via the Meta Ads Manager (formerly Facebook Ads Manager) integration. System User tokens are strongly recommended for server-to-server integrations to reduce re-authorization frequency.
Expiring System User tokens are valid for 60 days from the date generated or last refreshed. The token must be refreshed before expiry or a new one must be obtained.
Source Documentation: Meta – Access Token Guide
2. LinkedIn Ads
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (3-Legged Authorization Code Flow) |
| Access Token Lifetime | 60 days (expires_in: 5,184,000 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token |
| Renewal Credential Lifetime | Up to 1 year (refresh_token_expires_in: ~525,600 min / 31,536,000 sec) |
| Re-Authorization Requirement | Required when refresh token expires (~1 year) or is revoked |
| Trigger Events | Refresh token expiry (~365 days), user revokes app access, LinkedIn policy enforcement |
Implementation Notes
LinkedIn access tokens are valid for 60 days. Refresh tokens are valid for approximately 1 year (525,600 minutes as documented). After the refresh token expires, the user must complete the full OAuth authorization flow again.
LinkedIn does not support extending the refresh token beyond 365 days without full re-authorization. Applications should monitor token expiry and prompt re-authorization well before the 1-year window closes.
A programmatic refresh token flow is available for qualifying partners. Check the LinkedIn Programmatic Refresh Token documentation for eligibility.
Source Documentation: LinkedIn – Authorization Code Flow
3. TikTok Ads (Business API)
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (TikTok for Business Developer Portal) |
| Access Token Lifetime | 24 hours (86,400 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token |
| Renewal Credential Lifetime | Up to 1 year (31,536,000 sec); requires active daily refresh of the access token using the refresh token |
| Re-Authorization Requirement | Required when refresh token expires (~1 year) or is revoked |
| Trigger Events | Daily access token expiry, annual refresh token expiry (~1 year), app permission revocation by advertiser |
Implementation Notes
TikTok Business API access tokens expire every 24 hours and must be refreshed programmatically without requiring user interaction. Background refresh jobs are strongly recommended.
Refresh tokens are valid for 1 year. After 1 year, the advertiser must reauthorize the application through the full OAuth flow. This is a hard limit.
The TikTok Business API uses a separate token model from the TikTok consumer (creator) API. Ensure the correct developer portal (ads.tiktok.com) is used for the Claravine integration.
Source Documentation: TikTok – OAuth User Access Token Management
4. Google Ads
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (Web App or Installed App flow) |
| Access Token Lifetime | ~1 hour (3,600 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token |
| Renewal Credential Lifetime | No fixed expiration in production apps*; 7 days in testing/unverified app status |
| Re-Authorization Requirement | Rarely required. Required if: token is revoked, user removes app access, the 100-token-per-account limit is exceeded, or the app remains in 'Testing' status |
| Trigger Events | User revokes access, app remains in Testing status (7-day refresh token limit), 100 active refresh tokens per account per OAuth client ID exceeded, security-driven revocation |
Implementation Notes
Google client libraries handle access token refresh automatically. For production-status apps, refresh tokens do not expire on a fixed schedule.
If a Google Cloud project's OAuth consent screen is set to 'Testing' status, issued refresh tokens expire after 7 days. Publishing the app to 'In production' status removes this 7-day limit.
Google enforces a hard limit of 100 active refresh tokens per Google Account per OAuth 2.0 client ID. Exceeding this limit causes automatic invalidation of the oldest token — this is a common cause of unexpected re-authorization requirements when multiple connections share the same OAuth client.
Service accounts are recommended for production server-to-server integrations as they bypass user-level re-authorization requirements entirely.
Disclaimer: 'No fixed expiration' means the credential does not expire on a time schedule, but may still be invalidated by inactivity, revocation, security events, or platform policy changes. This is not a guarantee of permanent access.
Source Documentation: Google Ads API – Credential Management
5. Google Campaign Manager 360 (CM360)
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 or Service Account |
| Access Token Lifetime | ~1 hour (3,600 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token or Service Account key (automatic, no user interaction) |
| Renewal Credential Lifetime | No fixed expiration in production apps*; 7 days in testing mode. Service account keys do not expire unless rotated or revoked. |
| Re-Authorization Requirement | Not required for service accounts. For user OAuth: same conditions as Google Ads. |
| Trigger Events | User revokes access, 100-token limit reached per OAuth client ID, Testing-mode token expiry (7 days), service account key rotation |
Implementation Notes
Campaign Manager 360 follows Google's standard OAuth 2.0 infrastructure. All token lifecycle rules from Google Ads (testing mode limits, 100-token cap) apply equally here.
Service accounts are strongly recommended for server-side integrations. They eliminate user re-authorization dependencies and avoid the 100-refresh-token cap.
When using service account authentication, CM360 access must still be granted at the user profile level within the CM360 UI — the service account email must be added as a CM360 user.
Disclaimer: 'No fixed expiration' applies only to production-status apps. Service account key rotation is an operational responsibility — keys do not expire automatically but should be rotated per your organization's security policy.
Source Documentation: CM360 – Authorize Requests
6. Google Display & Video 360 (DV360)
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 or Service Account |
| Access Token Lifetime | ~1 hour (3,600 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token or Service Account key (automatic, no user interaction) |
| Renewal Credential Lifetime | No fixed expiration in production apps*; 7 days in testing mode. |
| Re-Authorization Requirement | Not required for service accounts. For user OAuth: same conditions as Google Ads. |
| Trigger Events | User revokes access, 100-token limit per OAuth client ID, Testing-mode token expiry, service account key rotation |
Implementation Notes
DV360 (Display & Video 360) uses the same Google OAuth 2.0 infrastructure and all the same token lifecycle rules as Google Ads and CM360.
The required OAuth scope for DV360 is https://www.googleapis.com/auth/display-video. Service accounts with the appropriate DV360 user role bypass interactive re-authorization.
The DV360 API also requires that the authenticating Google Account (or service account) be configured as a DV360 user with appropriate role permissions within the DV360 partner/advertiser settings.
Source Documentation: DV360 – Authorize Requests
7. Snapchat Ads
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (Snap Business Manager OAuth App) |
| Access Token Lifetime | ~1 hour (3,600 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token |
| Renewal Credential Lifetime | Not explicitly defined in public documentation; generally long-lived unless revoked. Implementations should treat refresh tokens as revocable at any time. |
| Re-Authorization Requirement | Required if the refresh token becomes invalid or is revoked |
| Trigger Events | User removes app authorization (via Manage Apps), OAuth App deleted or disabled by Org Admin, account security events |
Implementation Notes
Snapchat access tokens are valid for approximately 1 hour (expires_in: 3,600). A new access token is obtained by presenting the refresh token — this does not require user interaction.
Snapchat does not publish a fixed expiration duration for refresh tokens in public documentation. Refresh tokens should be treated as long-lived but revocable. Implement graceful handling for 401 errors and prompt re-authorization if the refresh flow fails.
OAuth Apps must be set up in Snap Business Manager by an Organization Admin. It is strongly recommended to use a shared organizational account (not a personal account) for authorization to prevent disruption if an employee leaves.
Users can revoke app access at any time via https://accounts.snapchat.com/accounts/oauth2/apps.
Disclaimer: Snap does not document a fixed refresh token expiration. The absence of a defined expiry in public docs does not guarantee indefinite validity. Handle token invalidation proactively.
Source Documentation: Snapchat – Marketing API Authentication
8. Pinterest Ads Manager
| Setting | Details |
|---|---|
| Auth Method | OAuth 2.0 (Authorization Code Grant) |
| Access Token Lifetime | Up to 30 days (2,592,000 sec) for the continuous refresh model |
| Token Renewal Mechanism | OAuth 2.0 refresh token (continuous/rolling model) |
| Renewal Credential Lifetime | 60-day rolling window, reset upon each successful refresh. Legacy 365-day non-rolling refresh tokens are no longer supported. |
| Re-Authorization Requirement | Required if the refresh token is not refreshed within its 60-day rolling window, or if it is revoked |
| Trigger Events | Refresh token not refreshed within 60-day window, user revokes app access, GitHub secret scanning auto-revocation (if token exposed in public repo) |
Implementation Notes
Pinterest deprecated the legacy 365-day non-rolling refresh token model. The current supported model issues a 'continuous refresh token' with a 60-day expiry that resets on each successful use, enabling indefinitely rolling access when refreshed regularly.
If a refresh token is not used within its 60-day window, it expires and the user must complete the full OAuth flow again.
Pinterest participates in GitHub secret scanning. If an access or refresh token is exposed in a public repository, Pinterest will automatically revoke it and notify the developer and associated user. Tokens should be stored in a secrets manager, never in code.
Pinterest supports both Authorization Code Grant (user-level, full API access) and Client Credentials Grant (app-level, limited scope). Claravine's integration uses the Authorization Code Grant for access to ad data.
Source Documentation: Pinterest – Authentication & Authorization
9. Amazon Ads
| Setting | Details |
|---|---|
| Auth Method | Login with Amazon (LWA) — OAuth 2.0 |
| Access Token Lifetime | ~1 hour (3,600 sec) |
| Token Renewal Mechanism | OAuth 2.0 refresh token (LWA) |
| Renewal Credential Lifetime | No fixed expiration for standard Ads API integrations; subject to revocation. Note: Amazon Selling Partner API (SP-API) integrations have a distinct 365-day annual re-authorization requirement — this does not apply to the standard Amazon Ads API. |
| Re-Authorization Requirement | Required if the LWA refresh token is revoked or authorization is removed by the account holder |
| Trigger Events | User removes app authorization, LWA refresh token revocation, security-driven invalidation |
Implementation Notes
Amazon Ads uses Login with Amazon (LWA) for OAuth 2.0 authentication. Access tokens expire after approximately 1 hour and are refreshed using the long-lived LWA refresh token.
LWA refresh tokens for the Amazon Ads API do not expire on a fixed schedule. They remain valid unless explicitly revoked or until the account holder removes application authorization.
Do not conflate Amazon Ads API behavior with Amazon Selling Partner API (SP-API). SP-API requires selling partners to re-authorize applications every 365 days — this annual requirement is SP-API-specific and does not apply to Claravine's Amazon Ads integration.
Authorization codes issued during the OAuth flow expire after 5 minutes and must be exchanged for a refresh token before expiry.
Disclaimer: 'No fixed expiration' for the LWA refresh token refers to the absence of a time-based expiry for standard Ads API integrations. The token remains subject to revocation and policy changes.
Source Documentation: Amazon – LWA Authorization Code Grant
10. The Trade Desk
| Setting | Details |
|---|---|
| Auth Method | Proprietary Token Authentication (not standard OAuth 2.0) |
| Access Token Lifetime | ~24 hours for short-lived tokens |
| Token Renewal Mechanism | Proprietary credential exchange (POST to /v3/authentication) or Long-Lived API Token (generated in TTD UI) |
| Renewal Credential Lifetime | Long-Lived API Tokens: no fixed expiration unless revoked. Short-lived tokens require re-authentication every ~24 hours. |
| Re-Authorization Requirement | Not required for Long-Lived API Tokens (unless revoked). Required approximately every 24 hours when using short-lived credential-exchange tokens. |
| Trigger Events | Token expiry (~24 hours for short-lived), token revocation, API access permission change, TTD account manager disables API access |
Implementation Notes
The Trade Desk uses a proprietary token model, not standard OAuth 2.0. Tokens are obtained by POSTing login credentials to /v3/authentication and the returned token is passed as 'TTD {token}' in the Authorization header.
Long-Lived API Tokens can be created in the Trade Desk UI under the user profile menu > Manage API Tokens. These are the recommended approach for production integrations with Claravine to avoid daily re-authentication.
API access must be explicitly enabled on the TTD account by a Trade Desk representative or account manager. Even with valid credentials, API calls will fail if the 'PublicAPI_General_View' scope (or additional required scopes) has not been enabled.
Short-lived tokens expire after approximately 24 hours. If using short-lived tokens, implement proactive credential refresh before expiry to avoid mid-session 401 errors.
Disclaimer: The Trade Desk Partner Portal documentation requires an authenticated login to access. Token behavior details in this document are based on available public documentation and partner-level information. Consult your TTD account manager for account-specific token configuration.
Source Documentation: The Trade Desk – API Authentication (Partner Portal login required)
General Best Practices
The following best practices apply across all Claravine social connectors:
- Use service accounts or system users where supported (Google platforms, Meta) to eliminate human re-authorization dependencies and improve stability.
- Implement proactive token refresh logic — do not wait for a 401 Unauthorized error to trigger a refresh. Refresh before the expiry window closes.
- Store refresh tokens and long-lived tokens securely using a secrets manager. Never commit tokens to code repositories.
- Designate a shared organizational account (not a personal user account) for OAuth authorization to prevent disruption when employees leave.
- Set calendar reminders or automated alerts for platforms with known hard re-authorization deadlines (LinkedIn ~1 year, TikTok ~1 year, Pinterest every 60 days if not auto-refreshed).
- Do not assume 'no fixed expiration' means permanent access — any token can be revoked. Implement graceful error handling and re-authorization flows.
- Monitor the Claravine Integration Activity Log regularly for connector errors. A failed sync is often the first indicator of a token issue.
- Subscribe to each platform's developer changelog or status page to stay informed of authentication policy changes.
- When using Google APIs, ensure your OAuth consent screen app is set to 'In production' status to avoid the 7-day refresh token limit imposed on 'Testing' status apps.
- For The Trade Desk, use Long-Lived API Tokens (not short-lived credential tokens) for Claravine production connections.
Footnotes & Disclaimers
The following notes clarify terminology and limitations used throughout this document. These clarifications are important for accurate interpretation in engineering, security, and audit contexts.
| Term / Platform | Clarification |
|---|---|
| No Fixed Expiration | Indicates that the credential does not expire automatically after a set time period, but may still be invalidated due to inactivity, user revocation, security events, or platform policy constraints. This is not a guarantee of permanent or indefinite access. |
| Meta Token Behavior | Meta does not implement OAuth refresh tokens in the standard sense. Long-lived tokens are extended or re-issued. System User tokens may not expire automatically depending on configuration, but this behavior is not universally guaranteed and remains subject to revocation or permission changes. |
| Snapchat Refresh Token Lifetime | Snapchat does not publish a fixed expiration duration for refresh tokens in public documentation. Implementations should assume tokens are long-lived but revocable. Handle token invalidation gracefully with fallback to the full OAuth flow. |
| Pinterest Rolling Refresh Model | Pinterest uses a rolling refresh token model where each successful refresh resets the expiration window. Failure to refresh within the defined 60-day window results in token expiry and requires full re-authorization. The legacy 365-day non-rolling token is no longer supported. |
| Amazon Ads vs. SP-API | Amazon Ads API (Login with Amazon / LWA) does not have an annual re-authorization requirement. The 365-day re-authorization applies specifically to the Amazon Selling Partner API (SP-API) and is not applicable to Claravine's Amazon Ads connector. |
| The Trade Desk Documentation Access | The Trade Desk Partner Portal documentation requires an authenticated partner login to access. Token behavior described in this document is sourced from available public documentation and partner-level information. Verify with your TTD account manager for account-specific details. |
Source Documentation Links
All token lifecycle details in this document are sourced from the official developer documentation of each respective platform. Links are provided below for reference and ongoing verification:
- Meta Ads Manager: https://developers.facebook.com/docs/facebook-login/guides/access-tokens/
- LinkedIn Ads: https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow
- TikTok Ads (Business API): https://developers.tiktok.com/doc/oauth-user-access-token-management
- Google Ads: https://developers.google.com/google-ads/api/docs/oauth/credential-management
- Google Campaign Manager 360 (CM360): https://developers.google.com/doubleclick-advertisers/authorizing
- Google Display & Video 360 (DV360): https://developers.google.com/display-video/api/guides/how-tos/authorizing
- Snapchat Ads: https://developers.snap.com/api/marketing-api/Ads-API/authentication
- Pinterest Ads Manager: https://developers.pinterest.com/docs/getting-started/set-up-authentication-and-authorization/
- Amazon Ads (Login with Amazon): https://developer.amazon.com/docs/login-with-amazon/authorization-code-grant.html
- The Trade Desk: https://partner.thetradedesk.com/v3/portal/api/doc/Authentication
- LinkedIn – Programmatic Refresh Tokens: https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens
- Google – OAuth 2.0 Token Expiration: https://developers.google.com/identity/protocols/oauth2
- Meta – Business System Users & Tokens: https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens/
- Claravine – Configure a Platform Connector: https://support.claravine.com/hc/en-us/articles/360015267512
Comments
0 comments
Please sign in to leave a comment.