NAV
shell

Introduction

Welcome to the AimBrain API spec.

Current API Version: API v1

Dashboard

The Dashboard for AimBrain On Demand allows you to create api-keys for your applications as well as debug the integrations.

Quick-start Guide

This guide will familiarise you with the concepts used in the AimBrain API and help you get started with the Dashboard

Create Your First Application

The first thing you need to do is create an Application. With AimBrain On Demand applications are an abstraction for a set of keys with specific permissions, each with its own event table.

Create Application

Enter the name of your Application, which you’ll use to find it in the dashboard, as well as keep the “DEBUG” box ticked. This will allow the events (api calls) to be stored in the dashboard. This functionality is meant to help with integarting AimBrain into your solutions.

Name your Application

After your Application is created, select it from the applications list.

Select your Application

Note the API Secret Key

From the top bar select “Application Settings”

Select Application Settings

On this page you can change your Application Name and check the API Secret Key and the Application Permissions (e.g. DEBUG). For now, we only care about the API Secret Key. It consists of the API Key and the API Secret. They are used in the authentication process against the API described here. It is critical to keep the API Secret secret.

Note down your API Secret Key

Setup the AimBrain CLI

The next step is downloading the AimBrain CLI tool.

Example setup for Ubuntu (any recent version) including dependencies:

sudo apt-get -y install python git libsm-dev libxrender-dev
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
git clone https://github.com/aimbrain/aimbrain-cli.git
cd aimbrain-cli/
pip install . --no-cache-dir

Example setup for Fedora including dependencies:

sudo yum -y install python git libSM-devel libXrender-devel libXext-devel
git clone https://github.com/aimbrain/aimbrain-cli.git
cd aimbrain-cli/
pip install . --no-cache-dir

Download the example images

Get the example images to use with the AimBrain CLI:

wget https://aimbrain.github.io/aimbrain-api/images/The_Hoff_1.jpg
wget https://aimbrain.github.io/aimbrain-api/images/The_Hoff_2.jpg
wget https://aimbrain.github.io/aimbrain-api/images/Pratt.jpg

Use the AimBrain CLI

Now that you have all the tools and examples ready, you can use the AimBrain CLI with your own credentials (which you noted down here).

For this example we will use the AimFace module. You can see the full functionality of the AimBrain CLI tool by running aimbrain-cli --help.

To enroll a face within your application with the AimBrain CLI run:

aimbrain-cli enroll face The_Hoff_1.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The command you’ll be using has 6 parameters:

enroll face indicates which functionality you want to use (in this case face enrollment)

The_Hoff_1.jpg indicates which image to use for the enrollment (subject to limits described here)

--user-id=the-hoff indicates the user ID for which the enrollment image will be used.

--api-key=<YOUR_API_KEY> indicates your API Key from the step above

--secret=<YOUR_API_SECRET> indicates your API Secret from the step above

At this point you’ll receive a response and some events will appear in your dashboard. To view them swith back to your dasboard and from the top bar select “Events”

View Events in the Dashboard

You should see two events there, one for the /v1/sessions(#v1-sessions) endpoint and one for /v1/face/enroll. There are a few things you can do here:

You can download the media you submitted to the endpoint by clicking “Download Media File”. This can be helpful when debugging applications to see if, for example, the media sent is not corrupted.

Download Media from the Dashboard

The other thing you can do is look at what responses were sent from the AimBrain API. You can do this by clicking the “Response” buttons.

View Enrollment Events the Dashboard

Understanding the Responses

Example enrollment response using the AimBrain CLI:

[/v1/sessions][200][0.22s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 0}
[/v1/face/enroll][200][0.90s] {u'imagesCount': 1}

As mentioned above, two calls are made to the AimBrain API when using the AimBrain CLI to enroll a face. One to /v1/sessions and one to /v1/face/enroll.

Every interaction with the AimBrain API begins with establishing a session. The responses let you know which Modules the user is enrolled for (for details on the response states please check the /v1/sessions) and proceed to either offer to enroll or authenticate. In our case, the response has 'face': 0 which means the user is not enrolled for face yet.

The session call also returns a long session id string to be used in all further calls in this session. Each session can have multiple calls to other endpoints.

The next step the AimBrain CLI did was send the media for enrollment to the face enrollment endpoint. The response 'imagesCount': 1 indicated that the image was of acceptable quality and was enrolled. This also returns a 200 HTTP code. In any other case, for example if image quality is poor (e.g. too dark) or no face is detected the AimBrain API returns 4xx errors (for details on the response states please check the /v1/face/enroll)

View Enrollment Events the Dashboard

Other Examples

Now that we’ve successfully enrolled a user we can try authenticating them. We can use the AimBrain CLI for that as well.

To authenticate a face belonging to the same person using the AimBrain CLI run:

aimbrain-cli auth face The_Hoff_2.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The command you’ll be using has 6 parameters:

auth face indicates which functionality you want to use (in this case face authentication)

The_Hoff_2.jpg indicates which image to use for the enrollment (subject to limits described here)

--user-id=the-hoff indicates the user ID for which the enrollment image will be used. We are using the same user-id as above, as it is already enrolled.

--api-key=<YOUR_API_KEY> indicates your API Key from the step above

--secret=<YOUR_API_SECRET> indicates your API Secret from the step above

Example authentication response using the AimBrain CLI:

[/v1/sessions][200][0.15s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 1}
[/v1/face/auth][200][0.64s] {u'liveliness': 0, u'score': 0.7880177}

As with the example above two calls are made. This time however the call to /v1/sessions returns 'face': 1. This means this user can use /v1/face/auth (otherwise there would be an error).

The response from the authentication endpoint has two fields:

'score': 0.7880177 which indicates the matching score. We recommend setting the authentication theshold to 0.5, meaning interpeting any score above 0.5 as a match. In this case, we can see there is a match.

'liveliness': 0 which indicates that the media did not contain a video of the person performing a valid response. In this case it is 0 because we were using a photo. Currently the liveliness system is set up to check if the person is blinking or not.

View Enrollment Events the Dashboard

Finally let’s try authenticating an impostor.

To authenticate a face belonging to a different person using the AimBrain CLI run:

aimbrain-cli auth face Pratt.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The only thing that changes from the example above is the image used, this time actually belonging to a different person.

Example authentication response using the AimBrain CLI:

[/v1/sessions][200][0.20s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 1}

[/v1/face/auth][200][0.76s] {u'liveliness': 0, u'score': 0}

As we can see from the response, we have 'score': 0 which indicates that the media definitelly does not match the enrolled user.

View Enrollment Events the Dashboard

Modules

AimBrain supports multiple biometric modalities (modules) as part of its authentication platform. These modules can be used together (e.g. to step-up the authentication on high risk actions) or separately, depending on the specific use-case. Because AimBrain offers a public API, any module can be used in a cross-channel context (e.g. same Voice Module with mobile banking application and customer call center).

At the core AimBrain uses advanced Deep Learning algorithms based on state of the art, PhD level, scientific research. The technology has multiple patents granted and pending in UK and US.

AimAnomaly

With the AimAnomaly module AimBrain flags abnormalities than could signal fraud, from the large scale right down to the manual onboarding stage. Even if you haven’t pinpointed the data patterns yet, we help you isolate and immobilise fraud, before it gets let in the door.

The technology works in mobile applications and websites.

AimBehaviour

With the behavioural modality AimBrain uses machine learning to track not what the user enters, but how they enter it. AimBrain monitors features such as touch pressure, typing speed, as well as movement.

The technology works in mobile applications and websites.

AimFace

The technology works in mobile applications and websites.

Liveliness detection done via random-challenge request.

AimVoice

The technology is language agnostic and supports free speech as well as set-phrase authentication.

Liveliness detection done via spoken challenge-response token.

Works in mobile apps, websites and call centres.

Security

AimBrain takes security very seriously. We adhere to the highest security industry standards and have daily penetration tests performed on the infrastructure and APIs.

API v1

All API requests use POST verb to prevent caching issues and request length limitations. Requests are passed in JSON format in the HTTP request body and MUST include the following header (alongside valid authentication headers):

Content-Type: application/json

Development Endpoint: https://api.aimbrain.com/

To offer lowest latency and thus best user experience to our clients we host our infrastructure in multiple regions. Please use a closest region to you when in production.

Region Name Region Production Endpoint
US East (N. Virginia) us-east-1 https://api.us-east-1.aimbrain.com/
US West (N. California) us-west-1 https://api.us-west-1.aimbrain.com/
US West (Oregon) us-west-2 https://api.us-west-2.aimbrain.com/
Asia Pacific (Mumbai) ap-south-1 https://api.ap-south-1.aimbrain.com/
Asia Pacific (Seoul) ap-northeast-2 https://api.ap-northeast-2.aimbrain.com/
Asia Pacific (Singapore) ap-southeast-1 https://api.ap-southeast-1.aimbrain.com/
Asia Pacific (Sydney) ap-southeast-2 https://api.ap-southeast-2.aimbrain.com/
Asia Pacific (Tokyo) ap-northeast-1 https://api.ap-northeast-1.aimbrain.com/
EU (Frankfurt) eu-central-1 https://api.eu-central-1.aimbrain.com/
EU (Ireland) eu-west-1 https://api.eu-west-1.aimbrain.com/
South America (São Paulo) sa-east-1 https://api.sa-east-1.aimbrain.com/

Architecture

Production architecture

AimBrain Production Architecture

Integration

This section provides an overview of how to integrate AimBrain into production systems as described in the architecture above. For specific SDK integration please view the relevant READMEs. The integration overview is provided as sequence diagrams below.

In these sequence diagrams interactions between the following components are shown:

Session

AimBrain Production Architecture

  1. iOS, Android
  2. iOS, Android

AimBehaviour

AimBrain Production Architecture

  1. iOS, Android
  2. iOS, Android

AimFace

AimBrain Production Architecture

  1. iOS, Android
  2. iOS auth, iOS enroll, Android auth, Android enroll
  3. /face/auth or /face/enroll endpoint

AimFace/LipSync

AimBrain Production Architecture

  1. iOS, Android
  2. iOS, Android
  3. iOS auth, iOS enroll, Android auth, Android enroll
  4. /face/auth or /face/enroll endpoint

AimVoice

AimBrain Production Architecture

  1. iOS, Android
  2. iOS, Android
  3. iOS auth, iOS enroll, Android auth, Android enroll
  4. /voice/auth or /voice/enroll endpoint

Authentication

To generate and run curl request using curl_hmac.py tool:

python2 curl_hmac.py test secret POST /v1/sessions\
    '{"userId": "user", "device":"device", "system":"system"}'

and to read request body from file:

python2 curl_hmac.py test secret POST /v1/sessions \
    -f "request_example_body.json"

Example output:

curl https://api.aimbrain.com:443/v1/sessions\
    -H 'Content-Type: application/json'\
    -H 'X-aimbrain-apikey: test'\
    -H 'X-aimbrain-signature: uPVe74VR9ncmxltwNX69pe6amFTMbJGM0Y8dIGk8vSI='\
    -d '{"userId": "user", "device":"device", "system":"system"}'

AimBrain uses API key pairs (API key and API secret) to allow access to the API. You can register a new API key by emailing us.

AimBrain expects for the API key and HMAC Signature to be included in all API requests to the server in the HTTP headers that look like the following:

X-aimbrain-apikey: api-key
X-aimbrain-signature: base64-hmac-signature

To make development, testing and debugging easier we provide a python tool for generating correctly signed and formed curl requests, as shown in the example.

Generating X-aimbrain-signature

Use base64 encoded HMAC SHA256 digest as the request signature:

X-aimbrain-signature = base64(HMAC_SHA256(secret, message)), where

secret is your API Secret, and

message = uppercase_http_method + '\n' + lovercase_endpoint + '\n' + request_body.

/v1/behavioural/submit

This endpoint sends behavioural data to the AimBrain backend to be used for the AimAnomaly score with the /v1/score call.

HTTP Request

POST /v1/behavioural/submit

Body

The data collection for AimAnomaly is facilitated by the SDKs and is application dependent. Data such as touch/type events, swipe/mouse movement events and accelerometer readings is gathered and sent.

HTTP Response

Status code: 200 OK

Errors

Please see #errors for description of errors and formatting.

/v1/score

Example response:

{
    "session":"test-session",
    "metadata":[],
    "scores":[
        {
            "version":"1.0.0",
            "type":"test-model",
            "value":1.0
        }
    ]
}

This endpoint returns the AimAnomaly score for the session.

HTTP Request

POST /v1/score

Body

Parameter Description
session
required
string
Current Session ID.

HTTP Response

Status code: 200 OK

Parameter Description
session string
Current Session ID.
metadata array of objects
Metadata associated with the session.
scores array of objects
Scores associated with the session.

metadata object:

Parameter Description
name string
Name of the metadata object (application specific).
value string
Value of the metadata object (application specific).

scores object:

Parameter Description
version string
Version of the scoring process used for this score object.
type string
Type of the scoring process used for this score object.
value float
Score returned by the scoring process in the range [0..1].

Errors

Please see #errors for description of errors and formatting.

/v1/sessions

Download session_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/sessions \
    -f 'session_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/sessions \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: E7vPXCNHsJQhadkTruAbCE+q9fCmRK9Gf+wtl2/3yrA=' \
    --data @session_request_example_body.json

Example response:

{
    "behaviour":0,
    "face":0,
    "voice":0,
    "session":"test-user-test-user-1234567890-1459141412877914289"
}

This endpoint creates a server-side session and returns unique session id to be used with further API requests.

HTTP Request

POST /v1/sessions

Body

Parameter Description
userId
required
string
Random anonymous static ID used to identify app users.
device
required
string
User’s device name used in the AimBehaviour Module and to calculate the precise accuracy by only testing between users with the same device.
system
required
string
Operating system’s name and version used for tracking SDK’s usage statistics.
screenHeight
required
integer
User’s device screen height (px).
screenWidth
required
integer
User’s device screen width (px).

HTTP Response

Status code: 200 OK

Parameter Description
session string
Generated session id for use with other API requests to maintain session semantics.
face integer
Status of the AimFace Module for given user (see below).
voice integer
Status of the AimVoice Module for given user (see below).
behaviour integer
Status of the AimBehaviour Module for given user and device pair (see below).

face parameter values:

Value Description
0 User not enrolled - facial authentication not available, enrollment required.
1 User enrolled - facial authentication available.
2 Building template - enrollment done, AimBrain is building user template and no further action is required.

voice parameter values:

Value Description
0 User not enrolled - voice authentication not available, enrollment required.
1 User enrolled - voice authentication available.
2 Building template - enrollment done, AimBrain is building user template and no further action is required.

behaviour parameter values:

Value Description
0 User not enrolled - behavioural authentication not available, enrollment required.
1 User enrolled - behavioural authentication available.

Errors

Please see #errors for description of errors and formatting.

/v1/behavioural

Example response:

{
    "status":0,
    "score":0
}

This endpoint enrolls and authenticates users based on the AimBehaviour Module.

HTTP Request

POST /v1/behavioural

Body

The data collection for AimBehaviour is facilitated by the SDKs and is application dependent. Data such as touch/type events, swipe/mouse movement events and accelerometer readings is gathered and sent.

HTTP Response

Status code: 200 OK

Parameter Description
score float
Probability, expressed as float between (0..1), that the current user is the original / enrolled user (only if the current user is already enrolled).
status integer
Status of the Behavioural Module for given user (see below).

status parameter values:

Value Description
0 User not enrolled - behavioural authentication not available, enrollment required.
1 User enrolled - behavioural authentication available.

Errors

Please see #errors for description of errors and formatting.

/v1/face/token

Download face_token_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/token \
    -f 'face_token_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/token \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: 9Dh+ODTM0YQ7ACEW+n+0B0I2NFBOmyRc21UyZ94J3+Q=' \
    --data @face_token_request_example_body.json

Example response:

{
    "token":"6-6-7"
}

This endpoint a token to be displayed during face/lipsync recording.

HTTP Request

POST /v1/face/token

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
tokentype
required
string
The type of token to be returned.

HTTP Response

Status code: 200 OK

Parameter Description
token string
The token to be displayed during face/lipsync recording.

tokentype parameter values:

Value Description
enroll-1 Token type to be used during the first enrollment step.
enroll-2 Token type to be used during the second enrollment step.
enroll-3 Token type to be used during the third enrollment step.
enroll-4 Token type to be used during the fourth enrollment step.
enroll-5 Token type to be used during the fifth enrollment step.
auth Token type to be used during authentication.

Errors

Please see #errors for description of errors and formatting.

/v1/face/enroll

Download face_enroll_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/enroll \
    -f 'face_enroll_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/enroll \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: VXNfJLbOntEVUlOp6UUwo8D4YyKjNtzspeBCOqZYM9A=' \
    --data @face_enroll_request_example_body.json

Example response:

{
    "imagesCount":2
}

This endpoint enrolls users based on the AimFace Module.

HTTP Request

POST /v1/face/enroll

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
faces
required
array of strings
List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter Description
imagesCount integer
Number of images accepted for enrollment.

Errors

Please see #errors for description of errors and formatting.

/v1/face/auth

Download face_auth_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/auth \
    -f 'face_auth_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/auth \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: dBxk9M++dNhI7pk+tXvAVaUwlWuOPl8S4wlmrhKhSqs=' \
    --data @face_auth_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness":0.05330102
}

This endpoint authenticates users based on the AimFace Module.

HTTP Request

POST /v1/face/auth

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
faces
required
array of strings
List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter Description
score float
Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
liveliness float
Probability, expressed as float between (0..1), that the received video in faces array represent a live person as opposed being still image. In case of images are sent in faces, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

/v1/face/compare

Download face_compare_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/compare \
    -f 'face_compare_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/compare \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: NwMmSbjqwsq7Y4x4Src7qHnIFerMhUTWcFxqLuAbbwg=' \
    --data @face_compare_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness1":0.05330102,
    "liveliness2":0.81412222
}

This endpoint compares two faces based on the AimFace Module.

HTTP Request

POST /v1/face/compare

Body

Parameter Description
faces1
required
array of strings
List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.
faces2
required
array of strings
List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter Description
score float
Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
liveliness1 float
Probability, expressed as float between (0..1), that the received video in faces1 array represent a live person as opposed being still image. In case of images are sent in faces1, 0.0 is returned.
liveliness2 float
Probability, expressed as float between (0..1), that the received video in faces2 array represent a live person as opposed being still image. In case of images are sent in faces2, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/token

Download voice_token_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/token \
    -f 'voice_token_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/token \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: isMJ65cfk0B4nJEx3YKroxrkTIkxlE0r/FJhyUVmgEQ=' \
    --data @voice_token_request_example_body.json

Example response:

{
    "token":"Hello, my password is 6-6-7, verify me"
}

This endpoint a token to be displayed during voice recording.

HTTP Request

POST /v1/voice/token

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
tokentype
required
string
The type of token to be returned.

HTTP Response

Status code: 200 OK

Parameter Description
token string
The token to be displayed during voice recording.

tokentype parameter values:

Value Description
enroll-1 Token type to be used during the first enrollment step.
enroll-2 Token type to be used during the second enrollment step.
enroll-3 Token type to be used during the third enrollment step.
enroll-4 Token type to be used during the fourth enrollment step.
enroll-5 Token type to be used during the fifth enrollment step.
auth Token type to be used during authentication.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/enroll

Download voice_enroll_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/enroll \
    -f 'voice_enroll_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/enroll \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: mUBC8eDZ45ObdC8IFll8gADoAsh70zGQcqPnYjVIsZI=' \
    --data @voice_enroll_request_example_body.json

Example response:

{
    "voiceSamples":1
}

This endpoint enrolls users based on the AimVoice Module.

HTTP Request

POST /v1/voice/enroll

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
voices
required
array of strings
List of base64 encoded voice samples of the user. 16k Hz sampling rate, 500kB maximum size. No longer than 5 seconds.

HTTP Response

Status code: 200 OK

Parameter Description
voiceSamples integer
Number of voice samples accepted for enrollment.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/auth

Download voice_auth_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/auth \
    -f 'voice_auth_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/auth \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: wVeNTVyYGGfy119x5kOLoisuRTBttyxxht/sJpLy7g8=' \
    --data @voice_auth_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness":1.0
}

This endpoint authenticates users based on the AimVoice Module.

HTTP Request

POST /v1/voice/auth

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
voices
required
array of strings
List of base64 encoded voice samples of the user. 16k Hz sampling rate, 500kB maximum size. No longer than 5 seconds.

HTTP Response

Status code: 200 OK

Parameter Description
score float
Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
liveliness float
Probability, expressed as float between (0..1), that the received voice samples in voices array represent a live person as opposed being a recording. In case voice token is not used, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

Errors

Example error:

{
    "error":"User not found",
    "errors":[
        {
            "description": "User not found",
            "code": 107
        }
    ]
}

All errors are indicated by returning HTTP code which is NOT 200. Human readable description as well as specific code is returned via body in JSON format.

Parameter Description
error string
Human readable error description of the main error.
errors array of objects
Array of all errors.

errors object

Parameter Description
description string
Human readable error description of the error.
code integer
Code of the error (list of possible error codes below).

HTTP error codes

The AimBrain API uses the following HTTP error codes in case of main errors:

Code Meaning Action
400 Bad Request – malformed request received (e.g. missing API key, API signature, required parameters or malformed json) Inspect the error message and fix any errors
401 Unauthorized – your API key or API signature is invalid Check implementation and try generating a new key pair via dashboard
403 Forbidden – specified session with the id could not be found Generate and include a valid session id and try again
422 Well formed request received, but images were not accepted (reason specified in error field) Capture a NEW set of images and try again
424 Well formed request received, but we could not find an enrolled user with the supplied id Confirm if enrollnment was done for the specific user
460 Token for the authentication request was not found Confirm if a token endpoint was called before authenticating
500 Internal Server Error – well formed request received, but we had a problem with our server Try again later

AimBrain error codes

Further to the HTTP error codes AimBrain also uses custom codes to facilitate the actionable feedback errors:

Code Meaning Action
1 Unable to detect a face in the photo/video Retake the photo/video
2 No image data in the face field Make sure the photo/video data is not corrupted
3 No facial points in photo/video Retake the photo/video
5 Image is blurred due to motion Retake the photo/video without shaking the camera
6 Face has wrong orientation Retake the photo/video upright
7 Detected face is far away Retake the photo/video while close to the camera
8 Image has poor sharpness Retake the photo/video in higher focus
9 Image has poor contrast Retake the photo/video in better lighting conditions
10 Image has poor brightness Retake the photo/video in better lighting conditions
11 Image is blurry Retake the photo/video in higher focus
12 Timeout processing liveliness Make sure the video adheres to required specifications
13 Image is malformed Make sure the photo is not corrupted
14 File received is too big Make sure the size of the request is less than 2 MB
15 Cannot read voice data Make sure the voice recording is not corrupted
16 Video and audio clips are of different durations Make sure the video is not corrupted
17 No media found Make sure the video is not corrupted
18 No video found Make sure the video is not corrupted
19 Cannot retrieve audio Make sure the video is not corrupted
20 Unsupported image type Make sure the photo is in a supported format
103 No user encodings Retry the request later
104 User cannot be enrolled Retry the request later
105 Cannot decode data Make sure the request is not malformed
106 Cannot decode request body Make sure the request is not malformed
107 User not found Make sure the user is enrolled
108 Unsupported MIME type Make sure the data is not corrupted
120 API error Retry the request later
150 No faces present in request Make sure the face data is present in the request
151 No voices present in request Make sure the voice data is present in the request
152 No token found Make sure the token endpoint was called prior to this request
153 No models found for the API key Please contact AimBrain
170 Operation timeout Retry the request later
180 Unsupported file type Make sure the data is not corrupted
181 Multiple file types detected Make sure the data is not corrupted
182 Cannot decode request body Make sure the data is not corrupted
999 Unknown error Retry the request later