NAV Navbar

Passbase Documentation

The Passbase Documentation offers ways to integrate via JavaScript snippet for web or mobile SDKs (iOS, Android or React Native). Please follow the integration guide for each platform.

If you have questions about the integration, discovered a bug or need help, you can reach out to us directly. Additionally we have a developer slack for integration help. Please email mathias@passbase.com if you want to be a invited.

Terminology

The "consumer-friendly" term Verification is used synonymously with Authentication, a more technical term. Authentication is the ability to prove that a person (End User) (or something abstract as an application or device) is genuinely who that person (or the application/device) claims to be.

Authentication example: A user takes a Selfie Video which proves that he is alive (Liveness) and sitting in front of the device capturing the information. He then proves (verifies) his Identity by providing some form of government-approved Identification Document (ID) (videos and pictures of it). The biometric information of the Selfie Video is matched against the photograph on the ID. A positive match (Facematch) authenticates a person on the system. The result of this process resembles an Authentication. The Document used for authentication has a certain DocumentType (e.g. Passport or National ID Card) and is attached to the Authentication. Further, DocumentInformation such as the first_names, last_name, document_number or expiration_date is extracted from this Document (e.g. a Video with many frames or pictures).

API Keys

You can create API keys in your Settings section or you will find it directly integrated in your code snippet, looking like a long hash. e.g. 4612a9022defviu6deb7c48cf5321247f2417c3d09cc9b56a0700ced57de.

There are two types of API keys, secret and publishable ones. A publishable API Key is used for the web button and within mobile Applications as it can be seen by anyone looking at the source code or on the web button's code snippet. It cannot be used for API calls to retrieve sensitive data. On the other side, a secret API Key can only be used for our private API. When a secret API Key is used in public setting and therefore potentially exposed, it will be deactivated and cannot be used anymore.

Web

To integrate the Passbase verification on your Website, please follow this guide and use your own API Key which you can obtain from the developer dashboard.

The integration of a Passbase Button for Web follows two simple steps:

  1. Include the code snippet with your API key
  2. Start a new verification process from a button

1. Include the javascript snippet

<!-- Place this before the </body> tag -->
<script type="text/javascript" src="https://dashboard.passbase.com/button.js"></script>

<!-- Place the code below where you want your button to appear -->
<div id="passbase-button"></div>

<script type="text/javascript">
Passbase.renderButton(document.getElementById("passbase-button"), (err, passport) => {
}, "{YOUR_API_KEY}",
{"additionalAttributes": {"customer_user_id": "YOUR_CUSTOMER_USER_ID"});
</script>

Navigate in your developer dashboard to the Integration section. You will see a code snippet like in the code section here.

Copy this snippet. It should already include an API key instead of {YOUR_API_KEY}. You can exchange that for different API keys if needed.

Optionally, you can pass more attributes with the {"additionalAttributes": {"customer_user_id": "YOUR_CUSTOMER_USER_ID"} field to our backend. This can later help you to identify your user when you receive information back via our API e.g. internal userId for your users.

2. Start the Verification

The button is now automatically rendered. Therefore, once you click on it, the verification popup should automatically start.

iOS

Follow this guide to integrate the Passbase SDK in your App and use your own publishable API Key which you can obtain from the developer dashboard.

The integration of the Passbase iOS SDK follows a few simple steps:

  1. Install the SDK through Cocoapods
  2. Initialization of the SDK with your API key
  3. Start a new verification process from a button
  4. Handling verifications

1. Install the SDK

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/facetec/cocoapods-specs.git'
source 'https://github.com/passbase/cocoapods-specs'

target 'YourApp' do
use_frameworks!

pod 'Passbase'

target 'YourAppTests' do
inherit! :search_paths
end

target 'YourAppUITests' do
inherit! :search_paths
end
end

We use Cocoapods as dependency manager. If you don't have it yet installed, please follow Step 1-2 from this guide Install Cocoapods.

If you don't have a Podfile in your project yet, create one. For this, open a terminal window and navigate to your iOS project's folder:

cd YourProject

pod init

This will create you a Podfile inside your project. Open this file and add the following code to it. First, add the following three lines at the top of your Podfile.

source 'https://github.com/CocoaPods/Specs.git'

source 'https://github.com/facetec/cocoapods-specs.git'

source 'https://github.com/passbase/cocoapods-specs.git'

Now add the actual pod after the target of your App.

pod 'Passbase'

See a full example on the right side to see where to place add it.

In order to install the SDK inside your project, go back to your terminal and run the following command inside your project folder:

pod install

This will install the Passbase SDK in your project and create a new .xcworkspace file inside your folder. Going forward, please use this file for future development, since all dependencies are installed here.

2. Initialize the SDK

Initialize the SDK in AppDelegate

// Add this to the top of your AppDelegate
import Passbase

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

  // Initialize the SDK with your API key
  Passbase.initialize(publishableApiKey: "YOUR_API_KEY")

  return true
}

Passbase uses API keys to allow access to the API and route it back to your dashboard. You need to register on our website to obtain an API key here: Developer Dashboard.

Open your Workspace File in your directory that has been created through the previous step with CocoaPods. It will be called something like YourProject.xcworkspace.

Now open your AppDelegate.swift file and add import Passbase to the top to import the Passbase SDK. After that, please add Passbase.initialize(publishableApiKey: "YOUR_API_KEY") within your didFinishLaunchingWithOptions function with your own API key. You can find your publishable API key under "Settings" and then API Access.

Adjust your App's permissions

You need to add the following permissions to your App's Info.plist, so that the Passbase SDK can verify a user:

alt text

3. Start the Verification

To start a new verification you can either trigger it through the Storyboard or by code. This section will walk you through both.

Start Verification through the StoryBoard

Two simple steps to get the button running:

  1. Just drag a new button on your storyboard and give it your desired constraints.
  2. Subclass the button as PassbaseButton. Ensure that the module also says Passbase below the class.

alt text

That's it. The button should now automatically be rendered and trigger the verification flow.

alt text

Start Verification programmatically

//Add to the top of the file
import Passbase

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    Passbase.delegate = self

    // Optional - You can pass additional attributes here or prefill the email to skip that step.
    Passbase.additionalAttributes = ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]
    Passbase.prefillUserEmail = "mathias.j.klenk@gmail.com"

    // Optional - UI Customizations e.g.:
    Passbase.buttonUI.actionButtonBgColor = .black

    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)

  }
}

To start the verification flow programmatically, create a new button of type PassbaseButton. You can give it parameters, like width, height, x & y through the CGRect and add constraint to position the button. Also you can give it a background color with 'bgColor'. We recommend to keep it UIColor.white for the moment but add more functionality to this over the next weeks.

Prefilling email address

If you wish that users don't have to enter their email, you can prefill it to skip the "Approve your Email" screen. Keep in mind, that some users may have different email addresses, that they signed up on Passbase with previously.

This is available programmatically if you pass the prefillUserEmail parameter to the button. See the code example.

Sending additionalAttributes

Also, you can pass additional attributes along with the additionalAttributes object (e.g. additionalAttributes: ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]). This can be useful, if you want to pass an internal user ID, identifiers or other information to our dashboard. Imagine, a user can have multiple email addresses or he / she may change it over a lifetime on your platform. With this field you will be able to link all verifications back to the same user. This is important if you use the reauthentication feature. See the code example.

4. Handling verifications


import Passbase
import UIKit

class ViewController: UIViewController, PassbaseDelegate {

  override func viewDidLoad() {
    super.viewDidLoad()

    Passbase.delegate = self

    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
  }

  func didCompletePassbaseVerification(authenticationKey: String) {
    print("didCompletePassbase with authenticationKey \(authenticationKey)")
  }

  func didCancelPassbase() {
    print("didCancelPassbase")
  }
}

Please set the delegate to self in the viewDidLoad method and add PassbaseDelegate to the class on top.

Then you can use the two delegate methods (didCompletePassbaseVerification and didCancelPassbase) to recognize if a verification was successful or a user cancelled it.

Also you get back an authenticationKey in the didCompletePassbaseVerification. With this key you can send requests to our API e.g. getting the status of a specific verification (approved or rejected). It might take a few minutes until a verification is fully processed and of course depend if you approve or reject it in your dashboard.

5. UI Customizations

//Add to the top of the file
import Passbase

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    Passbase.delegate = self

    // Optional - UI Customizations e.g.:
    // Button outside the flow to start
    Passbase.buttonUI.buttonBgColor: UIColor! = UIColor.white

    // Button inside the flow
    Passbase.buttonUI.tintColor: UIColor! = UIColor.passbaseBlue // Progress Bar & Loading Indicator
    Passbase.buttonUI.actionButtonBgColor: UIColor! = UIColor.black
    Passbase.buttonUI.actionButtonTextColor: UIColor! = UIColor.white
    Passbase.buttonUI.actionButtonFont: UIFont! = UIFont(name: "Helvetica", size: 17)

    // Disclaimer
    Passbase.buttonUI.disclaimerTextFont: UIFont! = UIFont(name: "Helvetica", size: 10)
    Passbase.buttonUI.disclaimerBoldTextFont: UIFont! = UIFont(name: "Helvetica", size: 10)
    Passbase.buttonUI.disclaimerTextColor: UIColor! = UIColor.lightGray

    // Titles of each steps
    Passbase.buttonUI.titleTextFont: UIFont! = UIFont(name: "Helvetica", size: 24)
    Passbase.buttonUI.titleTextColor: UIColor! = UIColor.black

    // Fonts
    Passbase.buttonUI.inputTextFont: UIFont! = UIFont(name: "Helvetica", size: 20)
    Passbase.buttonUI.mainFont: UIFont! = UIFont(name: "Helvetica", size: 17)
    Passbase.buttonUI.mainBoldFont: UIFont! = UIFont(name: "Helvetica", size: 17)
    Passbase.buttonUI.secondaryFont: UIFont! = UIFont(name: "Helvetica", size: 15)

    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
  }
}

We offer the possibility to customize the UI of the button itself and various elements during the flow. For example you can customize the color of the progress bar, button and different fonts. Check the code sample.

Android

To integrate the Passbase SDK follow this guide and use your own API Key which you can obtain from the developer dashboard.

The integration of the Passbase Android SDK follows a few simple steps:

  1. Install the SDK
  2. Initialization of the SDK with your API key
  3. Start a new verification process from a button
  4. Handling verifications

1. Install as Gradle Plugin

repositories {
  ...
  maven {
    url  'https://dl.bintray.com/passbase/android-sdk'
  }

  maven {
    url 'http://maven.facetec.com'
  }
}

Installing the Passbase Android library is simple using Android Studio and IntelliJ. You don’t need to clone a repo or download any files. Just add the following to your project’s build.gradle file, inside the dependencies section. on Module:app level add to repositories part.

dependencies {
  ...   
  implementation 'com.passbase:passbase_sdk:1.3.9'
}

After that, add implementation 'com.passbase:passbase_sdk:1.3.9' to your dependencies.

alt text

2. Initialize the SDK

Passbase uses API keys to allow access to the API and route it back to your dashboard. You need to register on our website to create a new Passbase API key here: Developer Dashboard.

Open now your MainActivity in your directory that has been created through the previous step. It will be called something like MainActivity

val passbaseRef = Passbase(YOUR_CONTEXT)
passbaseRef.initialize("YOUR_API_KEY")

Add import com.passbase.passbase_sdk.Passbase to the top to import the Passbase SDK. After that your need to initialize it like on the right side.

You must replace YOUR_API_KEY with your publishable API key from your dashboard. You can find your publishable API key under "Settings" and then API Access.

alt text

Prefilling email address

val passbaseRef = Passbase(YOUR_CONTEXT)
passbaseRef.initialize("YOUR_API_KEY", "testuser@passbase.com")

If you wish that users don't have to enter their email, you can prefill it to skip the "Approve your Email" screen. Keep in mind, that some users may have different email addresses, that they signed up on Passbase with previously.

Sending additionalAttributes

passbaseRef.initialize("YOUR_API_KEY", additionalAttributes = arrayOf(Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")))

Also, you can pass additional attributes along with the additionalAttributesobject (e.g. additionalAttributes = arrayOf(Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")). This can be useful, if you want to pass for example your internal user ID to our dashboard. Imagine, a user can have multiple email addresses or he / she may change it over a lifetime on your platform. With this field you will be able to link all verifications back to the same user. This is important if you use the reauthentication feature.

3. Start the Verification

To start verification, you must call the startVerification() method after initializing the instance.

passbaseRef.startVerification()

You can create a stylized Passbase button in your xml layout, or programmatically.

alt text

Layout / XML

<com.passbase.passbase_sdk.PassbaseButton
android:id="@+id/verificationButton"
android:layout_width="280dp"
android:layout_height="56dp"
app:layout_constraintTop_toBottomOf="@+id/textView"
app:layout_constraintEnd_toEndOf="parent"
android:layout_marginEnd="8dp"
android:layout_marginRight="8dp"
app:layout_constraintStart_toStartOf="parent"
android:layout_marginTop="24dp"
android:layout_marginLeft="8dp"
android:layout_marginStart="8dp"/>

In your xml layout add something like the example on the right.

Programmatically

Or initialize it programmatically: val varificationButton = PassbaseButton(YOUR_CONTEXT)

That's it. The button should now automatically be rendered like below.

alt text

PassbaseButton inherits from LinearLayout and you can use all the methods.

4. Handling verifications

passbaseRef.onCompletePassbase { authKey ->
  println("Passbase verification was finished with authKey $authKey")
}

passbaseRef.onCancelPassbase {
  println("Passbase verification was cancelled.")
}

The onCompletePassbase method give you the ability to react on if a user verification is finished. e.g. bring the user to another screen.

Also, you can use callbacks for checking if a verification was complete or cancelled. Inside the onCompletePassbase method, you get back the authKey. This key is helpful if you want to ping our API for what the status of a verification is e.g. if it was approved or rejected. It might take a few minutes until a verification is fully processed and of course depend if you approve or reject it in your dashboard.

5. UI Customizations

passbaseRef.setProgressBarColor(Color.RED)

passbaseRef.setActionButtonColor(Color.BLACK)

val font = ResourcesCompat.getFont(YOUR_CONTEXT, R.font.YOUR_FONT)
passbaseRef.setFont(font)

If you want to change the color of the ProgressBar from above, you can set it trough customization function:

passbaseRef.setProgressBarColor(Color.RED)

also, you can change the colors of all active buttons with:

passbaseRef.setActionButtonColor(Color.BLACK)

and change the text font with:

passbaseRef.setFont(font)

An example of the customizations are on the right side.

Example

import android.os.Bundle
import android.support.v7.app.AppCompatActivity
import com.passbase.passbase_sdk.Passbase
import com.passbase.passbase_sdk.PassbaseButton

class ExampleActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // PassbaseButton
    val button = findViewById<PassbaseButton>(R.id.verificationButton)
    button.setOnClickListener {

      val passbaseRef = Passbase(this)

      val additionalAttributes = arrayOf(
        Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x"),
        Pair("addEmail", "tetuser2@passbase.com")
      )

      passbaseRef.initialize(
        "YOUR_API_KEY",
        prefillUserEmail = "tetuser@passbasecom",   // optional parameter
        additionalAttributes = additionalAttributes     // optional parameter
      )

      passbaseRef.onCancelPassbase {
        println("MainActivity onCancelPassbase")
      }
      passbaseRef.onCompletePassbase { authKey ->
        println("MainActivity onCompletePassbase $authKey")
      }

      passbaseRef.setProgressBarColor(Color.RED)
      passbaseRef.setActionButtonColor(Color.BLACK)
      val font = ResourcesCompat.getFont(this, R.font.arial)
      passbaseRef.setFont(font)

      passbaseRef.startVerification()
    }
  }
}

A full code example can be found in the code section.

React Native

For instructions how to integrate the Passbase SDK on React Native, please follow this guide here.

Authentication Response API

The Authentication Response API is used if you want to retrieve information from your dashboard into your own backend. You can only use this API once you are not in the free plan anymore. This API will help you to access information about the status of verified users etc.

Get all authentications

{
  "authentication": {
    "key": "282d1bac-d4b0-4fb1-ad45-bd3ae9fc3826",
    "reviewed_at": "2019-05-13T11:25:10.964Z",
    "review_status": true,
    "created_at": "2019-05-10T15:36:26.320Z",
    "additional_attributes": {
      "customer_user_id": "YOUR_CUSTOMER_USER_ID"
    },
    "authentication_assessments": {
      "facematch": {
        "value": "0.9692430311639064"
      },
      "id_authenticity": {
        "value": "0.9961912662927438"
      },
      "liveness": {
        "value": "1.0"
      },
      "overall": {
        "value": "0.9884780991522167"
      }
    },
    "authentication_document": "NATIONAL_ID_CARD",
    "documents": [
      {
        "document_type": "NATIONAL_ID_CARD",
        "document_information": [
          {
            "key": "DOCUMENT_NUMBER",
            "value": "ABC12345678"
          },
          {
            "key": "NATIONALITY",
            "value": "Germany"
          },
          {
            "key": "DATE_OF_BIRTH",
            "value": "1970-07-20"
          },
          {
            "key": "PLACE_OF_BIRTH",
            "value": "Berlin"
          },
          {
            "key": "SEX",
            "value": "male"
          },
          {
            "key": "DATE_OF_ISSUE",
            "value": "2018-10-20"
          },
          {
            "key": "DATE_OF_EXPIRY",
            "value": "2028-10-20"
          },
          {
            "key": "AUTHORITY",
            "value": "Berlin"
          },
          {
            "key": "FIRST_NAMES",
            "value": "John Jimmy"
          },
          {
            "key": "LAST_NAME",
            "value": "Doe"
          }
        ]
      }
    ],
    "end_user": {
      "customer_user_id": "YOUR_CUSTOMER_USER_ID"
    }
  },
  "status": "success",
  "code": "200"
}

This endpoint will return you all your verifications.

Method GET
Endpoint https://app.passbase.com
Path /api/v1/authentications/by_key/{{uuid:key}}
Headers
KEY VALUE
Content-Type application/json
Authorization APIKEY {{secret_api_key}}

Request Body

{}

Errors

The Passbase API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.