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 five simple steps:

  1. Creating an organisation (only applicable if you are a company)
  2. Creating a Yoti application
  3. Front-end integration
  4. Installing the Yoti SDK
  5. 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 SDKs all the time! If your preferred language isn’t supported yet, please get in touch: and we will do our best to support you!

The languages/platforms that we currently support are:

JavaScript (Node.js):







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




We’ve included code snippets for each step of the integration process alongside the descriptions.

Integration steps

1. Creating an organisation

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

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

If you are using Yoti for personal use please skip this section and head to section 2.

Once you have created your Yoti, head over to on your desktop computer. To log in, open the Yoti app on your phone, tap Scan Code and scan the QR code displayed on your desktop screen.

Once there, you will need to fill out the form with the following questions:

Your organisation is now created. You will have the ability to add administrators to your organisation. This will allow multiple people to log in to the same organisation dashboard and create applications.

To add administrators:

Once you have completed this we will authorise your organisation and you can proceed to the next step and create a Yoti application.

2. Creating a Yoti application

Once you have created your organisation, the next step is to create an application. Head over to on your desktop computer and follow the next steps.

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.

If you are an organisation please navigate to your organisation page by clicking your profile face and selecting your organisation. If you are using Yoti for personal use please continue on your personal dashboard.

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

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.

3. Front-end integration

    <script src=""></script>

    <!-- This span will create the Yoti button -->
    <span data-yoti-application-id="your-app-id">
        Use Yoti

    <!-- This script snippet will also be required in your HTML 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 Yoti 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)

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

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

compile group: 'com.yoti', name: 'yoti-sdk-impl', version: '1.3'
go get ""
// 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
// 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. 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.

5. 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']

# or

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

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

require_once './vendor/autoload.php';
$client = new \Yoti\YotiClient('SDK_ID', 'path/to/your-application-pem-file.pem');
from yoti_python_sdk import Client

import com.yoti.api.client.ActivityDetails;
import com.yoti.api.client.Date;
import com.yoti.api.client.HumanProfile;
import com.yoti.api.client.HumanProfile.Gender;
import com.yoti.api.client.Image;
import com.yoti.api.client.YotiClient;
import com.yoti.api.client.YotiClientBuilder;
import static com.yoti.api.client.FileKeyPairSource.fromFile;

YotiClient client = YotiClientBuilder.newInstance()
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=<tokenEncryptedWithYourAppPrivateKey>

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 token to Yoti Client object, the SDK does the following:

Profile attributes

    .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']
$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 postalAddress = profile.getPostalAddress();
  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


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


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

If you have any other questions please do not hesitate to contact

Once we have answered your question we may contact you again to discuss Yoti products and services. If you’d prefer us not to do this, please let us know when you e-mail.