User Authenticator API

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

The User Authenticator API is built as a RESTful API hosted on the cloud. All requests and responses are encoded in JSON. The Youverse 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 Youverse, 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 Youverse as an OIDC identity provider.

For testing our passwordless login experience, please take a look at Youverse 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

Decentralized MPC User Authentication

The following endpoints leverage our proprietary decentralized multi-party computation (MPC) face matching algorithm, to deliver superior privacy-first user authentication with a simple API call.

Users biometric signatures are hashed and broken into multiple parts where each part is stored in different locations. Using this approach, there isn't a central database that if compromised could expose users biometric information.

The following endpoint extracts a biometric template from a user selfie, and matches it against the registration template, using MPC. Additionally, several quality checks are made to validate the selfie image.

POST | {base_url}/user_verification/decentralized

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.

To delete a previously registered user you can use the following endpoint:

DELETE |  {base_url}/user_verification/decentralized

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

User authentication (classic way, without MPC) - 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 (classic way, without MPC) - 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 Youverse's redirect action in Auth0.

We also have a Flask + Okta Hosted Login + Youverse 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.

On-prem deployment guide

We can provide a Docker image that can be installed on the client servers and provides access to the Decentralized Authentication API.

In this case, the users biometric signatures are hashed and broken into multiple parts locally, assuring a zero-knowledge and fully private authentication service.

After subscribing to our service, please contact us to get the credentials for downloading the docker image.

Deployment (Ubuntu)

Single container

Make sure you have Python and Docker installed:
```
sudo apt-get install docker.io python3-pip
```
Make sure to add your user to docker group if you are not using root:
```
sudo usermod -aG docker $USER
sudo reboot
```
Install AWS CLI:
```
sudo pip3 install awscli
```

Configure your AWS CLI credentials as provided by us.

aws configure
AWS Access Key ID: <YOUR_KEY_ID>
AWS Secret Access Key: <YOUR_SECRET_ACCESS_KEY>
Default region name: eu-west-1
Default output format: <None>

Login to Docker registry
```
aws ecr get-login-password | docker login --username AWS --password-stdin $DOCKER_URL
```
$DOCKER_URL should be replaced with the real URL of the docker image, provided by Youverse.
Pull the Decentralized Authentication API docker image:
```
docker pull $DOCKER_URL
```
The command to launch this image should be similar to:

docker run -p 5006:5006 --add-host host.docker.internal:host-gateway --env yk_x_api_key=<check your x-api-key in the dashboard> $DOCKER_URL

Or, alternatively:

docker run -p 5006:5006 --network="host" --env yk_x_api_key=<check your x-api-key in the dashboard> $DOCKER_URL

The Decentralized Authentication API will be available on the host at port 5006.

Running with docker compose

Our API can also run using Docker Compose. Please check our example docker-compose.yml file.

Scaling with Kubernetes

Prerequisites

You should have a functioning Kubernetes cluster with a configured kubectl.

Deploy Authentication API to the cluster

To get started, we will define a deployment named youverse-authentication-api by writing a YAML file.

Our YAML file will define a Deployment object that launches and manages our API container. You can check the provided file (youverse-authentication-api-deployment.yaml) as a baseline to use on your own cluster.

You can apply this file to deploy it to your cluster:

kubectl apply -f youverse-authentication-api-deployment.yaml

Expose Authentication API

As an example for exposing the Authentication API deployment, we will create a Kubernetes service with the default type ClusterIP, where the Service gets an IP address reachable only from inside the cluster. If you want to expose a Kubernetes Service outside the cluster, you will need to create a Service of type LoadBalancer. This type of Service spawns an External Load Balancer IP for a set of Pods, reachable via the internet.

The provided YAML file youverse-authentication-api-service.yaml will define a service of type ClusterIP that will be listening on port 5006.

To deploy this file to your cluster:

kubectl apply -f youverse-authentication-api-service.yaml

By using the provided service configuration, it would be listening on http://youverse-authentication-api.default.svc.cluster.local:5006.

We have now created our youverse-authentication-api deployment and service!

Get started

Products

IAM Integrations

User Authenticator API

Use cases

API endpoints

Decentralized MPC User Authentication

User authentication (classic way, without MPC) - Selfie image

User authentication (classic way, without MPC) - Biometric template

User data

User deletion

Schemas

Verify user request

Verify user template request

Verify user response

Error response

Forbidden response

User ID

User data response

Samples & SDKs

On-prem deployment guide

Deployment (Ubuntu)

Single container

Running with docker compose

Scaling with Kubernetes

Prerequisites

Deploy Authentication API to the cluster

Expose Authentication API