NAV Navbar

Passbase Documentation

The Passbase API is organized in a JavaScript snippet for web and mobile SDKs. Please follow the integration guide for your platform like in the navigation menu on the left side.

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

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. 4612a9022def10fd2846deb7c48cf5321247f2417c3d09cc9b56a0700ced57de.

There are two types of API keys, secret and public (exposed) ones. A public API Key is used for the web button, as it can be seen by anyone looking at the source code of the Javascript button snippet. It cannot be used for private APIs. Conversely, a secret API Key can only be used for a private API. When a secret API Key is used for a public API 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 a Passbase Button follows three 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 Your Snippet 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. you use an internal userId for your users. We use emails as identifiers for users.

2. Start the Verification

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

iOS

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 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', '~> 1.3.0'

  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 terminal and navigate to your iOS project's folder:

cd YourProject

pod init

You should have now a Podfile. 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', '~> 1.3.0'

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

To install the SDK inside your project, go back to your terminal. Run the following command inside your project:

pod install

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(apiKey: "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 create a new Passbase 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 add Passbase.initialize(apiKey: "YOUR_API_KEY") within your didFinishLaunchingWithOptions function with your own API key. You can find your API Key in the dashboard inside your "Your Snippet" or under "Settings" and then API section. It is e.g. 61700f92ccc92590a064251c150a8e65a82382a3f957c1b8799f851c3c0b2c57 in this hash:

Passbase.renderButton(document.getElementById("passbase-button"), (err, passport) => { }, '61700f92ccc92590a064251c150a8e65a82382a3f957c1b8799f851c3c0b2c57');

An example is again in the code section here on the right.

Adjust your App's permissions

You need to add the permission to your App's Info.plist, so that the Passbase SDK can access the Camera to 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 all the constraints you want.
  2. Subclass the button as PassbaseButton. Ensure that the module also says Passbase underneath the class.

alt text

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

alt text

Start Verification programmatically

//Add to the top of the file
import Passbase

class ViewController: UIViewController {

  override func viewDidLoad() {
      super.viewDidLoad()

      // Add the button for example here and position it - without email prefill
      let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60), bgColor: UIColor.white)

      // With Email prefill and additionalAttributes
      let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60), bgColor: UIColor.white, prefillUserEmail: "testuser@passbase.com", additionalAttributes: ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"])
      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.

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.

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 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.

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), bgColor: UIColor.white)
        self.view.addSubview(button)
    }

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

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

You can use two delegate methods (didCompletePassbaseVerification and didCancelPassbase) to recognize if a verification was successful or a user cancelled it. For that set the delegate of the Passbase object to self and subclass your class to PassbaseDelegate.

In the didCompletePassbaseVerification you get back a authenticationKey. With this key you can later ping our API for the status of a specific verification, e.g. if the verification was approved or rejected.

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-android:1.3.0'
}

After that, add implementation 'com.passbase:passbase-android:1.0.0' 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 personal API key from your dashboard.

alt text

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.

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 complete, AuthKey $authKey")
}

passbaseRef.onCancelPassbase {
    println("Passbase verification cancel")
}

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 obtain 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.

Example

Below is a screenshot of a full example.

alt text

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.