Introduction

Yoti is an identity checking system that allows organisations to verify who people are, online and in person. For consumers, it’s an app that helps them prove who they are and verify the identities of others.

This document will guide you through the configuration and implementation steps that are necessary in order for your back-end to be able to retrieve a user profile and complete a Login flow. The image below describes the login process and how your back-end integrates with the Yoti architecture.

Login Flow

Yoti provides a set of SDKs that take care of fetching users’ profiles from our servers using a one-time token that we provide to your back-end when a user scans your Yoti app’s QR code.

The integration process involves four simple steps:

  1. Creating a Yoti Application
  2. Front-end integration
  3. Installing the Yoti SDK
  4. Retrieving a profile

Languages & Plugins

If we already support your back-end language, integration is going to be pretty straightforward. We’re working on improving our SDK all the time! If your preferred language isn’t supported yet, please get in touch: sdksupport@yoti.com and we will do our best to support you!

The languages/platforms that we currently support are:

JavaScript (Node.js): https://github.com/getyoti/yoti-node-sdk

Ruby https://github.com/getyoti/yoti-ruby-sdk

PHP https://github.com/getyoti/yoti-php-sdk

Python https://github.com/getyoti/yoti-python-sdk

Java: https://github.com/getyoti/yoti-java-sdk

Go: https://github.com/getyoti/yoti-go-sdk

.NET: https://github.com/getyoti/yoti-dotnet-sdk

The content management systems (CMS) that we currently support are:

Drupal: https://www.drupal.org/project/yoti

Joomla: https://extensions.joomla.org/extensions/extension/access-a-security/yoti/

WordPress: https://wordpress.org/plugins/yoti/

We’ve included code snippets for each step of the integration process alongside the descriptions. In order to change the language of the snippet please select from the top left language menu.

Integration Steps

1. Creating a Yoti Application

Let’s get started on integrating Yoti with your site!

First, you will need to have the Yoti app on your phone. If you haven’t got it already, you can find it on both Google Play and the App Store.

Once you have created your Yoti, head over to https://www.yoti.com/dashboard on your desktop computer.

Log in to Dashboard

To log in, open the Yoti app on your phone, tap ‘Scan Code’ and scan the QR code displayed on your desktop computer.

Please Note: Once you have logged in to Dashboard, your phone will show a ‘connected’ screen. To keep your data secure, we make sure that only your phone can decipher it. For this reason, you’ll need to keep the Yoti app active whilst you are using Dashboard. If you leave the Yoti app, you will need to log in again.

Creating an Application

To create your Application, head over to the ‘Applications’ tab on the side menu. If this is your first time creating an Application, you will see a short explanation and a ‘GET STARTED’ button.

Details tab

Please fill out your details and upload your logo (currently this needs to be in .png format). Once you have finished filling out your details click the ‘CREATE’ button. You will see a notification when this is successful. After completing the Details tab, you’ll need to provide information in the other tabs.

Data Tab

Select which credentials you want to gather from your users when they scan your App’s QR code and click ‘SAVE’ at the bottom of the page.

Integration Tab

Setting your Callback URL ­- this will default to https://www.yoti.com/connect/thankyou where the user will get a simple thank you message once they have scanned your QR code.

Keys Tab

Contains the various IDs and the key pair for your Application.

Application ID: This is required for the Yoti button that you’ll add to your web app’s front end code.

Scenario ID: This is used for the button generator if you wish to have the QR code generate within your own webpage instead of redirecting to the Yoti Connect Page associated with your app.

Yoti client SDK ID: You will need this on your back­end to initialise the SDK and it is passed in each call to our servers.

You need to download the PEM file containing your private key in order to decrypt tokens, receipts and sign requests. Just click the DOWNLOAD KEY PAIR button in the Keys tab to download it. Please keep this safe ­as this PEM file is essential to Yoti integration and can only currently be downloaded once. Do not open the PEM file in a text editor/IDE as this can corrupt your private key.

Publishing your Application

Once you have completed the above steps, you will be able to publish your Yoti Application. To do this, simply flip the switch next to your page name from Draft to Published and your Yoti Application will be ready to use.

2. Front-end Integration

<head>
    <script src="https://sdk.yoti.com/clients/browser.2.0.0.js"></script>
</head>

<body>
    <!-- This span will create the Yoti button -->
    <span data-yoti-application-id="your-app-id">
        Log in with Yoti
    </span>

    <!-- This script snippet will also be required in your HTML body -->
    <script>
        _ybg.init()
    </script>
</body>

You will need to provide a button to allow your users to authenticate with Yoti. Upon clicking this button, the user will be redirected to your Yoti Application or Page, which contains a QR code for them to scan with their Yoti app on their smartphone. Note that mobile web users will skip the QR code scanning step, as they use the Yoti mobile app directly to authenticate.

Yoti provides a button generator for you to use for this purpose. In order to use the button generator, you will need to include the script in your HTML file. In the accompanying example, the button generator script has been added to the head of the html document.

This JavaScript library currently needs to be invoked - do this by calling _ybg.init() in the body of your html document. Don’t forget to add an html element with the attribute data-yoti-application-id in order for the button to be rendered on the page.

Attribute descriptions:

Name Required Default Options Purpose
data-yoti-application-id true n/a n/a Identifies the application identification to request. This is provided on your Application page in Yoti Dashboard (navigate to KEYS -> Application ID)
data-yoti-type false n/a popout, inline How the browser should react when the button is clicked. If omitted, the connect page opens in the same window frame. If you wish to open the connect page in a new window choose ‘popout’ and for an embedded QR code, choose ‘inline’
data-yoti-scenario-id false* n/a n/a Used to render the inline QR code. If you set the above to ‘inline’ you must set this attribute. This is provided on your Application page in Yoti Dashboard (navigate to KEYS -> Scenario ID)

3. Installing the Yoti SDK

npm install -S -E yoti
gem install yoti

# The gem provides a configuration generator for Ruby on Rails:

rails generate yoti:install
// Get the Yoti PHP SDK library via a Composer package
composer require yoti/yoti-php-sdk

// Or the following Composer dependency:
"require": {
    "yoti/yoti-php-sdk" : "1.0.*"
}
pip install yoti
// If you are using Maven, add the following dependency:
<dependency>
    <groupId>com.yoti</groupId>
    <artifactId>yoti-sdk-impl</artifactId>
    <version>1.3</version>
</dependency>

// If you are using Gradle, add the following dependency:

compile group: 'com.yoti', name: 'yoti-sdk-impl', version: '1.3'
go get "github.com/getyoti/yoti-go-sdk"
// To install the Yoti NuGet package you will need to install NuGet.

// To import the latest Yoti SDK into your project, enter the following
// command from NuGet Package Manager Console in Visual Studio:
Install-Package Yoti

// For other installation methods, see https://www.nuget.org/packages/Yoti
// To install the Yoti.Owin package, you can use:

Install-Package Yoti.Owin

Once you have a working button you can move on to installing the SDK.

To successfully integrate you will need the following information about your app from Dashboard:

There are three purposes for this pem file:

  1. Decrypting the token
  2. Signing your requests to our servers
  3. Decrypting the fetched user profile, so that the profile data can be consumed by your application

The Yoti SDKs are available via popular dependency management systems like maven, gradle and npm. Further details can be found on the pages of the specific projects.

Once you have added the Yoti SDK dependency to your project, it’s time to initialise a Yoti client as shown in the code snippet below.

4. Retrieving a Profile

const YotiClient = require('yoti')
const CLIENT_SDK_ID = 'your-client-sdk-id'
const PEM_PATH = 'path/to/your-application-pem-file.pem'
const PEM_KEY = fs.readFileSync(PEM_PATH)
var yotiClient = new YotiClient(CLIENT_SDK_ID, PEM_KEY)
Yoti.configuration do |c|
  c.yoti_client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
  c.yoti_key_file_path = ENV['YOTI_KEY_FILE_PATH']
end

# or

Yoti.configuration do |c|
  c.yoti_client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
  c.yoti_key = ENV['YOTI_KEY']
end

# Where *YOTI_KEY* is an environment variable that stores the content of the secret key:

# YOTI_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEp..."
<?php
require_once './vendor/autoload.php';
$client = new \Yoti\YotiClient('SDK_ID', 'path/to/your-application-pem-file.pem');
from yoti import Client

client = Client(YOTI_CLIENT_SDK_ID, YOTI_KEY_FILE_PATH)
import com.yoti.api.client.YotiClient;
import com.yoti.api.client.YotiClientBuilder;
import static com.yoti.api.client.FileKeyPairSource.fromFile;

YotiClient client = YotiClientBuilder.newInstance()
    .forApplication(<YOUR_CLIENT_SDK_ID>)
    .withKeyPair(fromFile(<PATH/TO/YOUR/APPLICATION/KEY_PAIR.pem>)).build();
sdkID := "your-sdk-id";
key, _ := ioutil.ReadFile("path/to/your-application-pem-file.pem")

client := yoti.YotiClient{
    SdkID: sdkID,
    Key: key}
const string SDK_ID = "your-sdk-id";
const string PEM_PATH = "path/to/your-application-pem-file.pem";

var privateKeyStream = System.IO.File.OpenText(PEM_PATH);
var yotiClient = new YotiClient(SDK_ID, privateKeyStream);

Back-end integration is all about receiving a token, decrypting it and using it to get a user profile.

When a user scans a Yoti QR code, Yoti makes a GET request to your callback URL, passing a token as a query string parameter named token.

An example of a complete callback URL would look like the following: https://your-callback-url?token=<tokenEncryptedWithYourAppPublicKey>

You can set and edit the callback URL within your Yoti Application under the INTEGRATION tab. Yoti will automatically prefix the URL with https://.

When your web application receives a token via the exposed endpoint as a query string parameter, you can easily retrieve the user profile. The user profile object provides a set of attributes corresponding to the user attributes you specified during the creation of your Yoti Application on Dashboard.

When you pass the Yoti Client the token, the following occurs:

Profile Attributes


yotiClient.getActivityDetails(token)
    .then((activityDetails) => {
        let userId = activityDetails.getUserId();
        let userAttributes = activityDetails.getUserProfile();
        let selfie = userAttributes.selfie;
        let familyName = userAttributes.familyName;
        let givenNames = userAttributes.givenNames;
        let phoneNumber = userAttributes.phoneNumber;
        let dateOfBirth = userAttributes.dateOfBirth;
        let postalAddress = userAttributes.postalAddress;
        let gender = userAttributes.gender;
        let nationality = userAttributes.nationality;
    })
yoti_activity_details = Yoti::Client.get_activity_details(yoti_token)
user_profile = yoti_activity_details.user_profile
user_details = {
  user_id: yoti_activity_details.user_id,
  selfie: user_profile['selfie'],
  given_names: user_profile['given_names'],
  family_name: user_profile['family_name'],
  phone_number: user_profile['phone_number'],
  email_address: user_profile['email_address'],
  date_of_birth: user_profile['date_of_birth'],
  postal_address: user_profile['postal_address'],
  gender: user_profile['gender'],
  nationality: user_profile['nationality']
}
<?php
$activityDetails = $client->getActivityDetails();
$userDetails = [
    'userId' => $activityDetails->getUserId(),
    'selfie' => $activityDetails->getSelfie(),
    'given_names' => $activityDetails->getGivenNames(),
    'family_name' => $activityDetails->getFamilyName(),
    'phone_number' => $activityDetails->getPhoneNumber(),
    'email_address' => $activityDetails->getEmailAddress(),
    'date_of_birth' => $activityDetails->getDateOfBirth(),
    'postal_address' => $activityDetails->getPostalAddress(),
    'gender' => $activityDetails->getGender(),
    'nationality' => $activityDetails->getNationality()
];
activity_details = client.get_activity_details(yoti_token)
user_details = {
    'user_id': activity_details.user_id,
    'selfie': activity_details.user_profile.get('selfie'),
    'given_names': activity_details.user_profile.get('given_names'),
    'family_name': activity_details.user_profile.get('family_name'),
    'phone_number': activity_details.user_profile.get('phone_number'),
    'email_address': activity_details.user_profile.get('email_address'),
    'date_of_birth': activity_details.user_profile.get('date_of_birth'),
    'postal_address': activity_details.user_profile.get('postal_address'),
    'gender': activity_details.user_profile.get('gender'),
    'nationality': activity_details.user_profile.get('nationality')
}
  ActivityDetails activityDetails = client.getActivityDetails(yotiToken);
  HumanProfile profile = activityDetails.getUserProfile();

  String userId = activityDetails.getUserId();
  String givenNames = profile.getGivenNames();
  String familyName = profile.getFamilyName();
  String phoneNumber = profile.getPhoneNumber();
  String emailAddress = profile.getEmailAddress();
  Date dateOfBirth = profile.getDateOfBirth();
  String address = profile.getAttribute("postal_address");
  Gender gender = profile.getGender();
  String nationality = profile.getNationality();
  Image selfie = profile.getSelfie();
profile, _ := client.GetUserProfile(yotiToken)
user_details := map[string]interface{}{
  "ID":           profile.ID,
  "GivenNames":   profile.GivenNames,
  "FamilyName":   profile.FamilyName,
  "MobileNumber": profile.MobileNumber,
  "EmailAddress": profile.EmailAddress,
  "DateOfBirth":  profile.DateOfBirth,
  "Address":      profile.Address,
  "Gender":       profile.Gender,
  "Nationality":  profile.Nationality,
  "selfie":       template.URL(profile.Selfie.URL())}
ActivityDetails activityDetails = yotiClient.GetActivityDetails(token);
YotiUserProfile yotiProfile = activityDetails.UserProfile;

string userId = yotiProfile.Id;
Image Selfie = yotiProfile.Selfie;
string SelfieURI = profile.Selfie.Base64URI;
string GivenNames = yotiProfile.GivenNames;
string FamilyName = yotiProfile.FamilyName;
string MobileNumber = yotiProfile.MobileNumber;
string EmailAddress = yotiProfile.EmailAddress;
DateTime? DateOfBirth = yotiProfile.DateOfBirth;
string Address = yotiProfile.Address;
string Gender = yotiProfile.Gender;
string Nationality = yotiProfile.Nationality;

The profile attributes are central to the SDK and allow you to see and work with the information that your users share with you. Please note that only the attributes you ask for in the DATA tab in Yoti Dashboard will be present.

Yoti Dashboard Attribute Name SDK Attribute Name
Photo selfie
Given Name(s) given_names
Family Name family_name
Mobile Number phone_number
Email Address email_address
Date of Birth date_of_birth
Address postal_address
Gender gender
Nationality nationality

Errors

The retrieve profile endpoint might return the following error codes:

Code Meaning
400 Bad Request – Any of the described query parameters is missing, or the request is wrongly formatted
401 Unauthorized – We couldn’t verify the request signature or any of the auth headers is missing
404 Not Found – The request is correctly signed but there is no profile for the provided token
500 Internal Server Error – Something went wrong during the transaction, user should log in again

Support

For more information, you can check out our Developer FAQs.

If you have any other questions please do not hesitate to contact sdksupport@yoti.com.