Implementation

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

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

Bridge flow

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

  1. To start request a BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. token from your backend and pass the generated bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. to your application
  2. Initialize Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. in your application by passing bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. to CitadelBridge.init
  3. 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..
  4. 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.
  5. Make an API request to Citadel API to get the data.

Integrating Bridge

Once you get the API keys and learn the basics of the Citadel 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 Citadel and allow you to access their accounts via the Citadel API. , 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 Citadel and allow you to access their accounts via the Citadel API. involves 3 steps.

  1. Use a script tag to load the bridge.js library from the Citadel servers (example below).
  2. Make a call to a backend API endpoint to retrieve a bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. from Citadel's backend.
  3. Initialize Bridge with CitadelBridge.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.citadelid.com/bridge.js"></script>
</head>
<body>
<script>
  // Step 2 - Call your back end to retrieve a bridge_token from citadel
  const bridgeToken = <%= Value returned by API call to acquire bridge_token %>

  // Step 3 - Initialize Bridge
  const bridge = CitadelBridge.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>

Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. can be embedded in mobile apps as a Webview. Check our iOS and Android quickstart for examples.

Authentication

Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. 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 Citadel and allow you to access their accounts via the Citadel API. 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 Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. into CitadelBridge.init your application is the one trying to initialize, thereby creating a secure front end environment for your users.

Parameters

PropertyDescriptionRequired
bridgeTokenThe bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. value returned by the Create Bridge Token API endpoint.required

Callbacks

CallbackDescriptionRequired
onLoadA function that is called when BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. has finished loading.optional
onEventA 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 Citadel and allow you to access their accounts via the Citadel API.. See events below.optional
onSuccessA 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 Citadel and allow you to access their accounts via the Citadel API.. 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
onCloseA function that is called when BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. closes.optional

onEvent types

Event TypeEvent PayloadDescription
LOADNoneWhen BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. module has finished loading
SUCCESSTaskDataWhen the user successfully connects to their payroll provider
LINK_CREATEDTaskDataWhen the user attempts to log in to their payroll provider
CLOSECloseDataWhen BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. closes
ERRORErrorDataWhen an error occurs during the payroll provider connection process

TaskData

NameTypeDescription
public_tokenstringA public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. that can be exchanged for an access_tokenaccess_token - A private token unique to a single Link. Used to access Link data and initiate any actions using the same Link.
task_idstringA unique identifier associated with an attempt to use a LinkLink - A connection to a payroll provider used to retrieve payroll data. to retrieve payroll data. Include this identifier when opening a support ticket for faster turnaround.
employerobjectAn object with employer data. Contains employer's name. Can be undefined for admin product type.
{
    "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
    "task_id": "2b0e7a7dec1d47678fec4e02af621cc0",
    "employer": {
      "name": "Facebook Demo"
    }
}

CloseData

NameTypeDescription
employerobjectAn object with employer data. Contains employer's name. Can be undefined if no employer was selected or product_type is admin.
{
   "employer": {
        "name": "Facebook Demo"
    }
}

ErrorData

NameTypeDescription
errorErrorSee Errors section for the reference
public_tokenstringThe public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. associated to this connection attempt. This field will only be available if the error returned is associated to 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..
task_idstringA unique identifier associated with an attempt to use a LinkLink - A connection to a payroll provider used to retrieve payroll data. to retrieve payroll data. Include this identifier when opening a support ticket for faster turnaround.
{
    "error": {
        "error_code": "LOGIN_ERROR",
        "error_message": "Username or password is incorrect",
        "error_type": "LINK_ERROR"
    },
    "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
    "task_id": "5ad1938450c54024bbc967a3a7dc9020"
}

Closing Bridge

To close the BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. 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 Citadel and allow you to access their accounts via the Citadel API. instance returned by init function.

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

NPM packages

For projects using npm you can use these packages


Did this page help you?