Trying the BioID Web Service REST API with cURL

First contact

Unix Shell Prompt

Let's try to do some hands-on REST with the BioID Web Service (BWS). You'll need to already have requested a trial instance. Then you can go to the BWS Management portal and register a client app. I did this and got an email telling me that it runs on storage bws with in partition 9184. After having created it I can see that it appears in the “Client Apps” tab with the identifier 115243460.9184.app.bioid.com. The app name is something you can choose yourself when registering a new one.

Screenshot of Client Apps tab

One last thing we need to get started is the password for accessing the BWS. You can get it by clicking on the edit button if you did not write it down initially. There, you can also request a new password—which is what I will do before posting this article.

For me, it spells KNGypodPwU9KYddwJRODxftP.

Give me a token

Now we're all set and as a first thing, point your browser of choice to https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42. You see that the assigned partition appears twice, once as the subdomain and once in the BCID-Parameter.

The BCID (Biometric Class ID) should be unique for every user. We'd normally spell it bws/9184/42, but for the REST service also accepts bws.9184.42, as forward slashes might look confusing. The BCID consists of the storage (bws), the partition (9184) and the user who we are inquiring about. This last part can be chosen freely. But beware that giving the same ID to several users or giving returning users new IDs basically sabotages everything.

What the browser displays is a plain-text string that—in my case—looks like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbmlkIjoiMjFkMmMxNzYtNWNhZC00Y2VhLTlmOTAtNzg1Y2M5M2NhMWJhIiwiY2xudCI6ImZzaGFycCIsImFwcCI6IjExNTI0MzQ2MC45MTg0LmFwcC5iaW9pZC5jb20iLCJiY2lkIjoiYndzLzkxODQvNDIiLCJ0YXNrIjoyNTksImlzcyI6IkJXUyIsImF1ZCI6Imh0dHBzOi8vYndzLmJpb2lkLmNvbSIsImV4cCI6MTQzMTk1NDI3NiwibmJmIjoxNDMxOTUzNjc2fQ.xrih0Rkaojaz UcqRSM-TlDirzDIY4TTxMa7ps1CQ_k4

This is your token that you'll need to do further inquiries about that user. We can also use the command line to get it. Assuming you have cURL installed, this will download the token to a text file:

curl -u 115243460.9184.app.bioid.com:KNGypodPwU9KYddwJRODxftP "https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42&task=enroll&livedetection=false" >token.txt

Anybody there?

Next, let's see if we already enrolled face images (we could also ask for voice) for user 42:

curl -vu 115243460.9184.app.bioid.com:KNGypodPwU9KYddwJRODxftP "https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face"

We have to use verbose mode (notice the -v switch) to see that we get back a HTTP/1.1 404 Not Found at the end of a lot of output and that means that we did not.

May I introduce…

Let's upload some pictures first. I have two gray-scale PNG images that I want to send. We need to convert them to a data URL first, which can easily be done here.

First face pictureSecond face image

After that, uploading is easy:

curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go" https://bws.bioid.com/extension/upload -d @a.png.txt
curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go" https://bws.bioid.com/extension/upload -d @b.png.txt

I shortened the token part, because it's really long, but you have to put all of it working. For both images I got the answer

{"Accepted":true,"Warnings":[],"Error":null}

After that, we tell the web service that these two files should be enrolled for the user 42. We don't have to specify the BCID again, because all this is encoded in the token.

curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go" https://bws.bioid.com/extension/enroll

Again, I get no error, which means that we have successfully enrolled our first user!

{"Success":true,"Error":""}

Checking

For a quick check:

curl -vu 115243460.9184.app.bioid.com:KNGypodPwU9KYddwJRODxftP "https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face"

gives a HTTP 200, which is what we expect. After getting a new token with task=verify (the old one invalidated anyway after one use) we can upload a third image of the same face and see if it is recognized.

curl -u 115243460.9184.app.bioid.com:KNGypodPwU9KYddwJRODxftP "https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42&task=verify&livedetection=false" >token.txt

Test face image


curl -H "Authorization: Bearer eyJ0eXAiOi…nRyhs0P1SY" https://bws.bioid.com/extension/upload -d @c.png.txt
curl -H "Authorization: Bearer eyJ0eXAiOi…nRyhs0P1SY" https://bws.bioid.com/extension/verify

All commands succeed and I'm happy.


Comments

Martin D Cernadas
Martin D Cernadas Wednesday, October 11, 2017

Excellent! It plays fine via CURL!


Leave a Comment

(optional, used for your Gravatar icon only)
(optional, your name links here)