Implementation Best Practices

Comprehensive guide covering OAuth implementation, testing strategies, and production deployment best practices. These guidelines apply to all Verified on LinkedIn tiers (Development, Lite, and Plus).

OAuth Scope Management

To provide the best user experience and avoid multiple authorization prompts, request all required OAuth scopes in a single authorization request.

Available Scopes by Tier:

Scope Purpose API Available In
r_profile_basicinfo Basic profile information (name, email, profile URL, picture) /identityMe All tiers
r_verify Verification categories (not detailed metadata) /verificationReport Development, Lite
r_verify_details Detailed verification status and metadata /verificationReport Plus only
r_most_recent_education Most recent education details /identityMe Plus only
r_primary_current_experience Current workplace information /identityMe Plus only

Authorization URL Examples

When redirecting members to LinkedIn for authorization, include all required scopes in the authorization URL, here are the example redirection URLs for different tiers:

Development/Lite Tier:

https://www.linkedin.com/oauth/v2/authorization?
  response_type=code&
  client_id={YOUR_CLIENT_ID}&
  redirect_uri={YOUR_REDIRECT_URI}&
  state={RANDOM_STATE}&
  scope=r_profile_basicinfo%20r_verify

Plus Tier:

https://www.linkedin.com/oauth/v2/authorization?
  response_type=code&
  client_id={YOUR_CLIENT_ID}&
  redirect_uri={YOUR_REDIRECT_URI}&
  state={RANDOM_STATE}&
  scope=r_verify_details%20r_profile_basicinfo%20r_most_recent_education%20r_primary_current_experience

Key Points:

  • Scopes are space-separated (URL-encoded as %20)
  • Request all scopes upfront to avoid re-authorization
  • Member grants consent once for all requested permissions
  • Reduces friction in the user experience

Why Request All Scopes Together?

✅ Single consent flow - Member authorizes once instead of multiple times
✅ Complete data access - Get all profile and verification data in one session
✅ Better UX - Avoid interrupting member with additional authorization requests
✅ Simplified implementation - No need to manage partial authorization states

User ID Management

ID Uniqueness Validation (Critical)

Requirement: You must validate that each id is unique in your system.

Why: Failing to validate uniqueness allows a single LinkedIn account to verify multiple accounts on your platform, creating a security vulnerability.

Note

Always use the id field (available since version 202510). The userId field will be deprecated in future versions and should only be used for temporary backward compatibility during migration from older API versions.

Best Practices

  • ✅ Enforce uniqueness at the database level (UNIQUE constraint)
  • ✅ Check for existing LinkedIn ID before saving new verification
  • ✅ Log security alerts when duplicate attempts are detected
  • ✅ Display clear error messages to members
  • ✅ Provide support contact for legitimate edge cases

Token Storage

Requirement: You must securely store OAuth access tokens and refresh tokens with encryption.

Why: Storing refresh tokens is necessary to generate new access tokens when needed to refresh member data without requiring the member to re-authorize. This enables you to keep member profile and verification information up-to-date through background processes.

Storage Best Practices

  • ✅ Encrypt tokens using AES-256-GCM or equivalent
  • ✅ Store in secure backend database with proper access controls
  • ✅ Implement token rotation and secure deletion policies
  • ✅ Never store tokens in client-side storage (cookies, localStorage, sessionStorage)
  • ✅ Log access to tokens for audit purposes

Testing Your Integration

Basic Test Flow

1. OAuth Flow Testing

  • ✅ Test successful authorization
  • ✅ Test member denies authorization (handle gracefully)
  • ✅ Test token expiry and refresh
  • ✅ Validate state parameter (CSRF protection)

2. API Testing

  • ✅ Call /identityMe with valid token
  • ✅ Call /verificationReport with valid token
  • ✅ Verify response fields (id, basicInfo, verifications)
  • ✅ Handle missing optional fields (email, profile picture)

3. Error Handling

  • ✅ Test with invalid token (401 error)
  • ✅ Test with insufficient scopes (403 error)
  • ✅ Handle API errors gracefully
  • ✅ Log errors for debugging

Test Variations

Verification Cases:

  • Fully verified (IDENTITY + WORKPLACE)
  • Partially verified (IDENTITY only or WORKPLACE only)
  • Unverified (empty verifications array)
  • Redirect Member to LinkedIn verification URL to add more verifications
  • Handle callback to Partner website on successful verification completion

Edge Cases:

  • Missing email address
  • Missing profile picture
  • Non-English names and locales, Special characters in names
  • Member has no verifications and not eligible for any verifications as well

Production Deployment

Pre-Production Checklist

Security:

  • ✅ Tokens encrypted at rest
  • ✅ Client secret in environment variables
  • ✅ HTTPS only for all API calls
  • ✅ State parameter implemented (CSRF protection)
  • ✅ Token refresh automated

API Integration:

  • ✅ Error handling for all API responses
  • ✅ Timeout handling (5s timeout for all endpoints and 30s timeout for /validationStatus)
  • ✅ Logging for errors and key events

Data Handling:

  • ✅ Member ID uniqueness enforced based on your business use case
  • ✅ Handle missing optional fields gracefully
  • ✅ Check image URL expiry before display

User Experience:

  • ✅ Follow branding guidelines
  • ✅ Handle unverified members gracefully
  • ✅ Clear success and error messaging
  • ✅ Mobile responsive design

Tier-Specific Guides

OAuth Guides

API References

Plus Tier Features

  • Last updated on