User Authenticator API


Welcome to User Authenticator API, an offering within YooniK Services.

The User Authenticator API is built as a RESTful API hosted on the cloud. All requests and responses are encoded in JSON. The YooniK User Authenticator API was designed to expose complex biometric functionalities via a simple REST API that can be integrated virtually in any programming language, in any environment.

Use cases

{primary} Passwordless login

User Authenticator API allows the creation of passwordless login applications in a simple and secure way.

We offer a Single Sign-On (SSO) service using OpenID Connect (OIDC) protocol along with multiple integrations with IAM Providers. To login with YooniK, you need a username and a selfie, and that’s it! No more passwords to worry about.

If you would like to test our SSO service for free, please send us an e-mail requesting a SSO service account and provide your app name, domain, and callback URL. You can also take a look at our Python example app using YooniK as an OIDC identity provider.

For testing our passwordless login experience, please take a look at YooniK Login.

{primary} Second factor authentication

User Authenticator API can also be used as a second-factor authentication method in conjunction with the most prominent identity and access management providers, such as Auth0, Okta and Onelogin.

API endpoints

User authentication - Selfie image

Endpoint that extracts a biometric template from a user selfie, and matches it against the registration template.

Additionally, several quality checks are made to validate the selfie image.

POST | {base_url}/user_verification

Accepts: Verify user request

{success} Success

Status Meaning Schema
200 OK Verify user response

{danger} Error responses

Status Meaning Schema
400 Bad Request Error response
401 Unauthorized Error response
403 Forbidden Forbidden response
405 Method Not Allowed Error response
409 Conflict Error response
500 Internal Server Error Error response

There are specific tags that can be present in the message field of a 400 Bad Request response:

Tags in the "message" field

Value Description
face_not_found Could not find a face in the image.
multiple_faces The image has more than one person.
brightness_failed Please take a selfie in an environment with good illumination.
light_uniformity_failed Try to avoid having parts of your face shadowed.
quality_failed The provided image does not have enough quality or liveness test failed.

User authentication - Biometric template

Endpoint that receives a previously extracted biometric template from a user selfie, and matches it against the registration template.

POST | {base_url}/user_verification/verify_template

Accepts: Verify user template request

{success} Success

Status Meaning Schema
200 OK Verify user response

{danger} Error responses

Status Meaning Schema
400 Bad Request Error response
401 Unauthorized Error response
403 Forbidden Forbidden response
405 Method Not Allowed Error response
409 Conflict Error response
500 Internal Server Error Error response

User data

Endpoint to retrieve user data.

POST | {base_url}/user_verification/user_data

Accepts: User ID

{success} Success

Status Meaning Schema
200 OK User data response

{danger} Error responses

Status Meaning Schema
400 Bad Request Error response
401 Unauthorized Error response
403 Forbidden Forbidden response
405 Method Not Allowed Error response
409 Conflict Error response
500 Internal Server Error Error response

User deletion

Endpoint that deletes all the data related to specified user.

DELETE |  {base_url}/user_verification

Accepts: User ID

{success} Success

Status Meaning Schema
204 No Content No schema

{danger} Error responses

Status Meaning Schema
400 Bad Request Error response
401 Unauthorized Error response
403 Forbidden Forbidden response
405 Method Not Allowed Error response
409 Conflict Error response
500 Internal Server Error Error response

Schemas

Verify user request

{
  "user_id": "string",
  "user_photo": "string",
  "create_if_new": true
}

Properties

Name Type Required Restrictions Description
user_id string True None User Id (to be used for recurrent verifications.
user_photo string True None Selfie image as BMP, PNG or JPG base 64 string.
create_if_new boolean True None Set True for registering the user if is new.

Verify user template request

{
  "user_id": "string",
  "template": "string",
  "template_version": "string"
}

Properties

Name Type Required Restrictions Description
user_id string True None User Id (to be used for recurrent verifications).
template string True None Biometric template as base64 string.
template_version string True None Version of the biometric template.

Verify user response

{
  "status": "string"
}

Properties

Name Type Required Restrictions Description
status string True None User verification status.

Enumerable types

Property Value Description
status SUCCESS Face authentication successful.
status NEW_USER Face signup successful.
status USER_NOT_FOUND User not registered.
status FAILED Face authentication failed.

Error response

{
  "status_code": 400,
  "phrase": "string",
  "message": "string"
}

Properties

Name Type Required Restrictions Description
status_code integer True None HTTP status code.
phrase string True None HTTP status code phrase.
message string True None Detailed error message.

Forbidden response

{
  "message": "Missing Authentication Token"
}

Properties

Name Type Required Restrictions Description
message string True None Detailed error message.

User ID

{
  "user_id": "string"
}

Properties

Name Type Required Restrictions Description
user_id string True None User Id.

User data response

{
  "template": "string",
  "template_version": "string"
}

Properties

Name Type Required Restrictions Description
template string True None Biometric template as base64 string.
template_version string True None Version of the biometric template.

Samples & SDKs

Please check our Sample Web App in Flask for capturing a selfie using the webcam and performing face authentication using this API. This sample app handles YooniK's redirect action in Auth0.

We also have a Flask + Okta Hosted Login + YooniK Face Authentication example app that shows how to use Flask to log in to your application with an Okta Hosted Login page. The user first logs in using Okta-Hosted login, and then we perform a second-factor face authentication using this API.

Finally, you can check our OpenID Connect example app here.