Onboarding vs Account Update

Overview

This guide specifies two authentication workflows for managing LinkedIn account credentials: initial account onboarding and token refresh for existing authenticated accounts.

Workflow Selection

1. Onboarding Flow (New Account)

Endpoint: POST /tokens/onboarding

Trigger: First-time account connection

Action: Save both token and refreshToken for the current onboarding process so the iframe can make the necessary API calls

🔗Step-by-step Guide: https://salesflow.apidocumentation.com/documentation/initial-setup/iframe-integration/#connect-a-new-linkedin-account

Use case:

1. User doesn’t have LinkedIn account with this email and wants to add it into your system (NEW account)

2. Update Flow (Re-authentication)

Endpoint: POST /api/v1/tokens/jwt

Trigger conditions:

• status != ACCOUNT_ACTIVE
  ❗ If status ≠ active → trigger update flow

🔗Step-by-step Guide: https://salesflow.apidocumentation.com/documentation/initial-setup/iframe-integration/#update-an-existing-linkedin-account

Use case :

1. System gets webhook that account is status = ACCOUNT_BLOCKED

2. User has LinkedIn account with this email but this account is DISCONNECTED (blocked)

Tokens

Token Type	Lifespan	Used For	Refreshed Via
token (access token)	-	Update iFrame operations	refreshToken parameter
refreshToken	Long-lived, persistent	Obtaining new access tokens via /tokens/jwt endpoint; used internally by our iframe to perform necessary API calls for onboarding and account updates	-
Onboarding token	30 minutes	Single onboarding operation	-

Critical Rules

✅ DO

• Use update flow (/api/v1/tokens/jwt) for all re-authentication

• Check account status before operations

❌ DO NOT

• Delete and recreate accounts to reset authentication (triggers API rate-limiting)

• Treat onboarding flow as repeatable for existing accounts