📚 Tutorials
Integrate Data Sync

Data Sync - Integration Guide

Once you have successfully signed up for Portabl and configured your Data Profile, you're ready to start integrating Data Sync which involves two parts:

  • Implementing two REST API endpoints at your server-side
    • Get Sync Context endpoint
    • Prepare Sync endpoint
  • Integrating Data Sync widget at your client-side
    • the widget shall integrate given API endpoints for its life-cycle events

Backend Configuration

Get Sync Context endpoint

Step # 1 - Integrate Get Access Token endpoint

  • The Portabl Core™ API uses API keys to authenticate requests.
  • You can view and manage your API keys in the Portabl Console.
  • Your API keys grant extensive access to Portabl Core™ API, so make sure to not share them to publicly accessible areas such client-side code, repositories, etc.
  • Authentication to the API is performed via OAuth 2.0 Client Credentials Grant flow.

Step # 2 - Pick a User ID

  • Pick an identifier that will serve as a unique external user id within Portabl Core™ API.
  • Subject to implementation of your auth server, you might consider passing and validating you native auth params, and derive a user id from them.

Step # 3 - Integrate Get Sync Context endpoint

  • Fetches all relevant information for determining whether the user is synced or not, as well as, the scope for performing a data synchronization.

Prepare Sync endpoint

Step # 1 - Integrate Get Access Token endpoint

  • The Portabl Core™ API uses API keys to authenticate requests.
  • You can view and manage your API keys in the Portabl Console.
  • Your API keys grant extensive access to Portabl Core™ API, so make sure to not share them to publicly accessible areas such client-side code, repositories, etc.
  • Authentication to the API is performed via OAuth 2.0 Client Credentials Grant flow.

Step # 2 - Pick a User ID

  • Pick an identifier that will serve as a unique external user id within Portabl Core™ API.
  • Subject to implementation of your auth server, you might consider passing and validating you native auth params, and derive a user id from them.

Step # 3 - Integrate Create or update a user endpoint

  • Data synchronization should be enabled for a user by passing the following request body:
    • { settings: { isSyncOn: true } }
  • If a user is not found within your Portabl account yet, one will be created.
  • Otherwise, if a user is found, it will update user settings and set data synchronization flag to true.

Step # 4 - Integrate Create User Invitation endpoint

  • Creates a user invitation url in case a secure session with a given user has not yet been established.
    • e.g. { isSessionEstablished: false, isLinked: false, invitationUrl: 'https://api.getportabl.com/connect?_oob=eyJ...xfQ' }
  • This invitation shall be accepted by a given user to establish a secure session.
  • Once established, this session can be used to securely deliver messages between SSI agents for data synchronization.
  • If a secure session with a given user is already establish then "isAlreadyConnected" in the response body will be set to true, and no invitation url will be returned
    • e.g. { isSessionEstablished: true }

Step # 5 - Fetch user's identity data from internal API(s)

Step # 6 - Integrate Patch User Claims endpoint

  • Patches claims of a user.
  • By default, patching user claims will start the data synchronization process.
  • To disable this behavior and control when data synchronization should start you can provide "noAutoSync=false" in your query params.

Step # 7 - Integrate Start User Data Sync (Manual Trigger) endpoint

  • It manually kicks-off data synchronization process over a previously established secure session.
  • The process involves user authentication, issuance and delivery of a verifiable credential which includes claims of a given user.
  • This can be useful for providers with distributed systems that do not want to rely on automatic data synchronization and have greater control.
  • By using this manual trigger you can batch claim patches together and manually trigger a synchronization by request.

Widget integration

After successfully configuring and setting up the necessary scaffolding for data synchronization, you can proceed with integrating a client-side Sync Widget using the Sync Widget SDK. This integration will allow your users to initiate the Data Synchronization process from within your application.

We offer the Sync Widget SDK in various different libraries. Please select the desired library and follow the integration steps specific to that library.

Register WebhooksIntegrate Connect