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.

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

Custom Errors

No custom errors. Please see #errors for description of standard errors.

/v1/behavioural

Download behavioural_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/behavioural \
    -f 'behavioural_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/behavioural \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: TgDm+IwKlW3H3ILdB3ga0OOZGgZab4gM/9nW+X4NSHw=' \
    --data @behavioural_request_example_body.json

Example response:

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

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

HTTP Request

POST /v1/behavioural

Body

Parameter Description
session
required
string
Current Session ID as returned by /v1/sessions request.
touches
required
array of objects
List of touch events (see below).
accelerations
required
array of objects
List of accelerometer events (see below).
textEvents
required
array of objects
List of text change / typing events (see below).

touches object:

Parameter Description
tid
required
integer
Touch id as reported by the system (e.g. MotionEvent.getPointerId(int)) for Android
p
required
integer
Phase or action for the touch event, where: 0 - Began, 1 - Moved, 2 - Stationary, 3 - Ended, 4 - Cancelled.
t
required
integer
The the time (in ms) when this specific event was generated.
x
required
integer
Absolute X coordinate for the touch position (for elements tagged as sensitive MUST be reported as “0”).
y
required
integer
Absolute X coordinate for the touch position (for elements tagged as sensitive MUST be reported as “0”).
rx
required
integer
Relative X coordinate to the event element (e.g. button).
ry
required
integer
Relative Y coordinate to the event element (e.g. button).
r
required
float
Approximate size of touch area for the given touch id.
f
required
float
Force of pressure of touch for the given event.
ids
required
array of strings
List of identifiers of views in the order that touch event is propagating (for elements tagged as sensitive it MUST be reported as a hash of element id + locally generated salt which never leaves the user’s device).

accelerations object:

Parameter Description
t
required
integer
The the time (in ms) when this specific event was generated.
x
required
float
Acceleration in X direction.
y
required
float
Acceleration in Y direction.
z
required
float
Acceleration in Z direction.

textEvents object:

Parameter Description
t
required
integer
The the time (in ms) when this specific event was generated.
tx
required
string
Full text after the event / change.
ids
required
array of strings
List of identifiers of views in the order that touch event is propagating (for elements tagged as sensitive it MUST be reported as a hash of element id + locally generated salt which never leaves the user’s device).

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.

Custom Errors

No custom errors. Please see #errors for description of standard errors.

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

Custom Errors

No custom errors. Please see #errors for description of standard errors.

/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, JPEG and PNG 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.

Custom Errors

Code Meaning Action
422 Well formed request received, but images were not accepted (reason specified in error field) Capture a NEW set of images and try again

Please also see #errors for description of standard errors.

/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, JPEG and PNG 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.

Custom Errors

Code Meaning Action
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

Please also see #errors for description of standard errors.

/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, JPEG and PNG 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, JPEG and PNG 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.

Custom Errors

Code Meaning Action
422 Well formed request received, but images were not accepted (reason specified in error field) Capture a NEW set of images and try again

Please also see #errors for description of standard errors.

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

Custom Errors

No custom errors. Please see #errors for description of standard errors.

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

Please also see #errors for description of standard errors.

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

Custom Errors

Code Meaning Action
460 Voice Token for the authentication request was not found Confirm if /v1/voice/token was called before authenticating
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

Please also see #errors for description of standard errors.

Errors

Example error:

{
    "error":"Unable to detect face in target image"
}

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

Parameter Description
error string
Human readable error description.

The AimBrain API uses the following error codes:

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
500 Internal Server Error – well formed request received, but we had a problem with our server Try again later

Authenticator

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

Endpoint: https://authenticator.aimbrain.com/

Authentication

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

python2 curl_hmac_authenticator.py bank secret POST /v1/requests\
    '{"ids":["XXXXXXXX"],"timeout":180,"modules":[0],"threshold":0.5,"attempts":3,"title":"Title","summary":"Summary"}'

Example output:

curl https://authenticator.aimbrain.com:443/v1/requests\
    -H 'Content-Type: application/json'\
    -H 'X-aimbrain-apikey: bank'\
    -H 'X-aimbrain-signature: /1vf7VfMHoLPcKgRBqTqATpP16MqoyyA3e05SgxtSxQ='\
    -d '{"ids":["XXXXXXXX"],"timeout":180,"modules":[0],"threshold":0.5,"attempts":3,"title":"Title","summary":"Summary"}'

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.

/requests

Example use:

python2 curl_hmac_authenticator.py bank secret POST /v1/requests\
    '{"ids":["XXXXXXXX"],"timeout":180,"modules":[0],"threshold":0.5,"attempts":3,"title":"Title","summary":"Summary"}' -r

Alternatively:

curl https://authenticator.aimbrain.com:443/v1/requests
    -H 'Content-Type: application/json'
    -H 'X-aimbrain-apikey: bank'
    -H 'X-aimbrain-signature: /1vf7VfMHoLPcKgRBqTqATpP16MqoyyA3e05SgxtSxQ='
    -d '{"ids":["XXXXXXXX"],"timeout":180,"modules":[0],"threshold":0.5,"attempts":3,"title":"Title","summary":"Summary"}'

Example response:

{
    "requestid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Create new authentication request. Returns unique authentication ID which reflects the authentication request progress.

HTTP Request

POST /requests

Body

Parameter Description
ids
required
array of strings
List of authenticator IDs that the client wants to push notification to. More than one usually represents multiple devices held by the user.
threshold
required
number
Threshold (probability) of when we consider user successfully authenticated between 0..1. 0 - definitely not the user, 1 - definitely the user.
modules
required
array of integers
A list of allowed modules for authentication (0 - face, 1 - voice).
attempts
required
integer
Number of attempts that the user can fail authentication before considering the original authentication request as failed.
timeout
required
integer
A timeout, in Seconds, from the original authentication request after which it is considered as failed.
title
required
string
Title to show the user when requesting authentication.
summary
required
string
Summary to show the user when requesting authentication.
meta
optional
string
Custom field which will be included with response, limited to 1024 characters.

HTTP Response

Status code: 200 OK

Parameter Description
requestid string
A unique request id used for tracking the authentication request progress. Different from the one sent to the app.

Custom Errors

No custom errors. Please see #errors for description of standard errors.

/requests/REQUESTID/status

Example use:

python2 curl_hmac_authenticator.py bank secret \
  POST /v1/requests/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/status/ '' -r

Alternatively:

curl https://authenticator.aimbrain.com:443/v1/requests/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/status/
    -H 'Content-Type: application/json'
    -H 'X-aimbrain-apikey: bank'
    -H 'X-aimbrain-signature: yqgQpOzesjoUeEbIsqVNRilxKHewn8vX40qA6TCPza8='
    -d ''

Example response:

{
    "created":1488477936,
    "remaining_attempts":3,
    "remaining_time":0,
    "status":2,
    "attempts":[{
        "timestamp":1488477944,
        "id":"XXXXXXXXXX",
        "score":0.9908461,
        "module":0
    }],
    "request":{
        "timeout":180,
        "modules":[0],
        "ids":["XXXXXXXXXX"],
        "threshold":0.5,
        "attempts":3,
        "title":"Title",
        "summary":"Summary",
        "meta":""
    }
}

Query for the authentication request progress. Here the REQUESTID is the requestid from the /requests call response.

HTTP Request

POST /requests/REQUESTID/status

Body

No body is required with this request. The requestid is passed through the URL.

HTTP Response

Status code: 200 OK

Parameter Description
remaining_attempts integer
Remaining attempts.
remaining_time integer
Remaining time in seconds.
created integer
UTC timestamp.
status integer
Status of the authentication request (see below).
attempts array of objects
List of authentication attempts (see below).
request object
JSON Object to represent the original request parameters (see below).

status parameter values:

Value Description
0 Request created.
1 Notification sent.
2 Authenticated successfully.
3 Failed to authenticate within allowed attempts.
4 Failed to authenticate within allowed time (timed out).
5 User alerted the authentication request.
6 Other reason for failed authentication.

attempts object fields:

Field Description
module Modules used.
score Score of authentication.
id Authenticator ID used.
timestamp UTC timestamp.

request object fields:

Field Description
ids array of strings
List of authenticator IDs as sent originally.
threshold number
Threshold (probability) as sent originally.
modules array of integers
List of allowed modules as sent originally.
attempts integer
Number of attempts as sent originially.
timeout integer
Timeout as sent originally.
title string
Title as sent originally.
summary string
Summary as sent originally.
meta string
Custom meta info as sent originally.

Custom Errors

No custom errors. Please see #errors for description of standard errors.

Errors

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

Parameter Description
error string
Human readable error description.

The AimBrain API uses the following error codes:

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
500 Internal Server Error – well formed request received, but we had a problem with our server Try again later