​
Usage

The Sync API and Permissions API authorize with a Paragon User Token. Add this token to the Authorization header of your requests to the Sync API or Permissions API:

Authorization: Bearer {user_token}

For testing purposes, you can use our Hosted Demo Environment to generate and copy a Paragon User Token in your browser that you can use with Managed Sync.

Required audience claim in token

Ensure that your Paragon User Token includes an aud claim with your Paragon instance hostname and Project ID. While not required for other Paragon APIs, the aud claim is required for Managed Sync.

If you are using your existing Paragon User Token, update your JWT generation code to include the aud claim with your Paragon instance hostname and Project ID.

JWT Payload
{
    "sub": "your-customer-id",
    "aud": "useparagon.com/{your-project-id}",
    "exp": 1752000000,
    "iat": 1751000000
}

See code examples of encoding your JWT using your project’s Signing Key in the Connect SDK documentation.

​
Sync Lifecycle

After you Enable a Sync for one of your users, Syncs run through the following lifecycle:

  • Initial sync: When the sync is first enabled, Paragon will pull all data from the integration (limited by any sync-specific filters) and index the records for later retrieval and change detection.
    • You will receive a sync_completed webhook when the initial sync is complete.
    • The Sync status will have an IDLE status and a lastSyncedAt timestamp when the initial sync is complete.
  • Incremental syncs: After the initial sync, Paragon will check periodically for changes to the data.
    • When records are created or updated, you will receive record_created or record_updated webhook events with metadata about the affected records.
    • The frequency of incremental syncs is every minute by default, but can vary by integration. See integration-specific details in Integrations Reference.
  • Periodic full sync: Every 24 hours, Paragon will perform a full refresh of your users’ data to detect any content drift or deletions that are not visible by incremental syncs.
    • After a periodic full sync runs, you may receive a batch of record_deleted webhook events for content that is no longer accessible by the Sync (meaning that the record was deleted or unshared from the connecting account).

​
Implementing Sync API

To implement Sync API in a production context, your application will need to handle initial and incremental sync phases, as illustrated below:

Initial sync:

  1. Enable the sync for a user.
  2. Poll the Sync API to check on the status of the sync or wait for a sync_completed webhook.
  3. Paginate through the records in the sync and pull them into your database or RAG pipeline.

Incremental syncs:

To handle ongoing updates, you can either:

  • Poll the Sync API for new or updated records, using the cursor property to get records synced after the last record you pulled.
  • Wait for record_created and record_updated webhooks to trigger when new or updated records are available.