X Bookmarks Integration

Arivu supports importing X bookmarks through server-side OAuth + API sync.

Prerequisites

• X Developer app with OAuth 2.0 enabled
• Confidential client credentials (client_id, client_secret)
• Public app URL where users can complete OAuth callback

Required X App Settings

In X Developer Portal:

• App type: Web App
• OAuth callback URL: https://your-domain.example/settings?section=connections
• Scopes:
  • bookmark.read
  • tweet.read
  • users.read
  • offline.access

Arivu Environment Variables

Set in .env:

X_INTEGRATION_ENABLED=true
X_CLIENT_ID=your_x_client_id
X_CLIENT_SECRET=your_x_client_secret
# Optional override (defaults to {APP_URL}/settings?section=connections)
X_REDIRECT_URI=https://your-domain.example/settings?section=connections
# Optional sync caps
X_MAX_BOOKMARK_PAGES=10
X_MAX_BOOKMARKS=300

Restart backend after changes:

docker compose -f docker-compose.prod.yml up -d backend

Validate Integration

1. Open Arivu Settings -> Connections
2. Click Connect X
3. Complete OAuth consent
4. Confirm connected account metadata appears
5. Click Sync Bookmarks
6. Verify imported items in dashboard

Operational Notes

• Sync status values include idle, syncing, auth_expired, rate_limited, error
• Dedup uses both x_tweet_id and normalized URL
• Sync limits can be relaxed by setting caps to 0 where supported

Troubleshooting

X integration disabled

• X_INTEGRATION_ENABLED is false
• Backend was not restarted after env change

OAuth callback fails

• Redirect URI mismatch between X app and Arivu
• Invalid client credentials
• State expired due long delay before callback completion

Sync runs but imports nothing

• No new bookmarks in X account
• Existing imports already deduplicated
• Sync cap reached in prior run

Reference Files

• backend/server.py
• frontend/src/components/settings/ConnectionsSection.jsx
• .env.example