Truv BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. is a drop-in module that your users will use to connect their accounts to Truv and allow you to access their data via Truv's API. Bridge will handle employer search, credentials, multi-factor authentication, and error handling.

We recommend starting with Quickstart to understand how Truv BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. can be implemented in your code.

Bridge flow

Below you can see an overview of tokens and data exchange between your application, Truv BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv., your backend, Truv and providers.

To start request a BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. token from your backend and pass the generated bridge_tokenbridge_token - A short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration. to your application
Initialize Truv BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. in your application by passing bridge_tokenbridge_token - A short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration. to TruvBridge.init
When a user successfully connects their account, a public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. is generated. Bridge hands off the public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. client-side via the onSuccess callback once a user has successfully created a LinkLink - A connection to a payroll provider used to retrieve payroll data..
Exchange a temporary public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. for a permanent access_tokenaccess_token - A private token unique to a single Link. Used to access Link data and initiate any actions using the same Link.
Make an API request to Truv to get the data.

Integrating Bridge

Once you get the API keys and learn the basics of the Truv API, it's time to integrate with BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. , which will handle credential validation, multi-factor authentication, and error handling for each integration that we support. Integrating with BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. involves 3 steps.

Use a script tag to load the bridge.js library from the Truv servers (example below).
Make a call to a backend API endpoint to retrieve a bridge_tokenbridge_token - A short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration. from Truv's backend.
Initialize Bridge with TruvBridge.init, passing the bridge_token received as a parameter.

<html>
<head>
    <!-- Step 1 - add the Bridge library to your app with a script tag -->
    <script src="https://cdn.truv.com/bridge.js"></script>
</head>
<body>
<script>
  // Step 2 - Call your back end to retrieve a bridge_token from truv
  const bridgeToken = <%= Value returned by API call to acquire bridge_token %>

  // Step 3 - Initialize Bridge
  const bridge = TruvBridge.init({
        bridgeToken: bridgeToken.bridge_token,
        onLoad:function(){
          // Optional, called when Bridge loads
          console.log('Bridge loaded')
        },
        onSuccess:function(public_token, metadata){
          console.log('success handler')
          // Send the public_token to your server to exchange for an access_token
          // and retrieve payroll data.
          // The metadata object contains info about the Link.
          console.log("token: ", public_token)
          console.log("metadata: ", metadata)
        },
        onEvent: function(event_type, payload) {
          // all events fire this function. event_type indicates what the event is,
          // payload has additional information depending on the event.
          console.log('event: ', event_type)
          console.log('payload: ', payload)
        },
        onClose:function(){
          // Optional, called when Bridge is closed by the user.
          console.log('Bridge closed')
        }
    })
</script>
<!-- Normal page content -->
<!-- Step 4 - Create a button or action that calls bridge.open() to Bridge -->
<button type="button" id="button" onclick="bridge.open()">
  Connect
</button>
</body>
</html>

NPM packages

For projects using npm you can use these packages

Authentication

Truv BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. is only meant to be used in authorized environments, so to ensure it is indeed your application requesting to initialize BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. we have you request a token from a secure setting (your back end) with your Client IDClient ID - The unique identifier passed into the X-Access-Client-Id header of every API request to authorize it. and Access keyAccess key - The unique key passed into the X-Access-Secret header of every API request to authorize it.. By passing the resulting bridge_tokenbridge_token - A short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration. into TruvBridge.init your application is the one trying to initialize, thereby creating a secure front end environment for your users.

Parameters

Property	Description	Required
bridgeToken	The bridge_tokenbridge_token - A short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration. value returned by the Create Bridge Token API endpoint.	required

Callbacks

Callback	Description	Required
onLoad	A function that is called when BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. has finished loading.	optional
onEvent	A function that is called when an event occurs with BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv.. See events.	optional
onSuccess	A function that is called when a user has successfully connected to a payroll provider and closed BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv.. The function should expect two arguments, the public_tokenpublic_token - A short-lived token used to exchange for an access_token from the backend. This token has a 6 hour expiration. and a metadata object.	required
onClose	A function that is called when BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. closes.	optional

Closing Bridge

To close the BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. programmatically (the default behavior is to wait for the user to close it) call close method of the BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Truv and allow you to access their accounts via the Truv. instance returned by init function.

// call close method of the bridge instance
bridge.close();