Mobile-ID authentication process in Dokobit Identity API

Please be aware that the access_token parameter must be sent with every request.

Successful authentication process requires to use only two endpoints:

1. /v2/mobile/login.json (for initializating authentication process)

2. /v2/mobile/login/status/{token}.json (for checking authentication status)

You can check more documentation at https://developers.dokobit.com/api/doc.

1. /v2/mobile/login.json

First of all, you have to make a POST request to "/v2/mobile/login.json" with two required params - phone number and personal code.

 REQUEST
 URL: https://developers.dokobit.com/v2/mobile/login.json?access_token=YOUR_ACCESS_TOKEN
 METHOD: POST
 BODY: phone=+37200000766&code=60001019906

 RESPONSE
 {
     "status": "ok",
     "token": "AUTHENTICATION_TOKEN",
     "control_code": "4231",
     "name": "MARY ÄNN",
     "surname": "O’CONNEŽ-ŠUSLIK TESTNUMBER",
     "code": "60001019906",
     "country": "LT",
     "certificate": {...}
 }
 or
 {
     "status": "error",
     "message": "Not a mobile signature user",
     "error_code": 6001
 }

After receiving this response, make sure to display "control_code" for the user because they need to verify that this control code is the same as they see one in their mobile device.

2. /v2/mobile/login/status/{token}.json

Now you need to start checking the status of the authentication process by making a GET request to "/v2/mobile/login/status/AUTHENTICATION_TOKEN.json". You should do it every 3 seconds until other than {"status":"waiting"} response is returned and no longer than 120 seconds.

 REQUEST
 URL: https://developers.dokobit.com/v2/mobile/login/status/AUTHENTICATION_TOKEN.json?access_token=YOUR_ACCESS_TOKEN
 METHOD: GET
 RESPONSE 
 {
   "status": "ok",
   "name": "MARY ÄNN",
   "surname": "O’CONNEŽ-ŠUSLIK TESTNUMBER",
   "code": "60001019906",
   "country": "EE",
   "certificate": {
     "name": "/C=EE/O=ESTEID (MOBIIL-ID)/OU=authentication/CN=O\\xE2\\x80\\x99CONNE\\xC5\\xBD-\\xC5\\xA0USLIK TESTNUMBER,MARY \\xC3\\x84NN,60001019906/SN=O\\xE2\\x80\\x99CONNE\\xC5\\xBD-\\xC5\\xA0USLIK TESTNUMBER/GN=MARY \\xC3\\x84NN/serialNumber=60001019906",
     "subject": {
       "country": "EE",
       "organisation": "ESTEID (MOBIIL-ID)",
       "organisation_unit": "authentication",
       "common_name": "O’CONNEŽ-ŠUSLIK TESTNUMBER,MARY ÄNN,60001019906",
       "surname": "O’CONNEŽ-ŠUSLIK TESTNUMBER",
       "name": "MARY ÄNN",
       "serial_number": "60001019906"
     },
     "issuer": {
       "country": "EE",
       "organisation": "AS Sertifitseerimiskeskus",
       "common_name": "TEST of ESTEID-SK 2015"
     },
     "valid_from": "2018-08-09T14:20:27+00:00",
     "valid_to": "2022-12-11T21:59:59+00:00",
     "value": "Base64 encoded PEM certificate"
   }
 }
 or
 {
     "status": "waiting"
 }
 or
 {
     "status": "error",
     "message": "Sending request to phone failed",
     "error_code": 7022
 }

When you receive a successful response with the status "ok", the authentication process is finished. You can authorize users by using their personal code and country received in the first request.

If you received a response with a status different than "waiting", you need to stop requesting the status of that session and inform the user with an error message.

If you need to translate errors to other languages, please use the error_code value from the response (error codes with their meanings can be found here).

After successful integration, you can test authentication scenarios with the data here.

Mobile-ID authentication process in Dokobit Identity API

Related Articles