ID Authentication APIs
This section details about the REST services in ID Authentication module.

Authentication Service (Public)

This service details authentication methods that can be used by authentication partners to authenticate an individual. Below are various authentication types currently supported by this service:
  • OTP based - OTP (Time based OTP)
  • Demographic based - Name, Date of Birth, Age, Gender, Address, Full Address
  • Biometric based - Fingerprint, Iris and Face

Users of Authentication service

  1. 1.
    MISP (MOSIP Infrastructure Service Provider) - MISP's role is limited to infrastructure provisioning and acting as a gate keeper for all authentication requests sent to this service. The MISP is also responsible for the policy creation on the MOSIP servers so their partners will follow the set policy.
  2. 2.
    Authentication Partners - Authentication Partners register themselves with MOSIP, under a MISP. Authentication requests are captured by authentication partners and sent to MOSIP, via MISP.
  3. 3.
    Partner-API-Key - Associated against a policy.

POST /idauthentication/v1/auth/

This request will authenticate an individual, based on provided authentication type(s).

Resource URL

https://{base_url}/idauthentication/v1/auth/{:MISP-LicenseKey}/{:Auth-Partner-ID}/{:Partner-Api-Key}

Resource Details

Resource Details
Description
Response format
JSON
Requires Authentication
Yes

Request Header Parameters

Name
Required
Description
Authorization
Y
For consent token
Signature
Y
For signature of the authentication request

Request Path Parameters

Name
Required
Description
MISP-LicenseKey
Y
License key provided to the MISP
eKYC-Partner-ID
Y
Partner ID of the authentication partner sending the request
Partner-API-Key
Y
API Key associated to the partner and the policy

Request Body Parameters

Name
Required
Description
id
Y
This represents the API ID. The value here should be "mosip.identity.auth".
version
Y
This represents the version of the API.
transactionID
Y
This represents the Transaction ID of the request.
requestTime
Y
This represents the time when request was created. Ex: "2019-02-15T10:01:57.086+05:30".
env
Y
This represents the environment. Allowed values are "Staging"
domainUri
Y
This represents the Unique URI per auth providers. This can be used to federate across multiple providers or countries or unions.
requestedAuth
Y
This represents the authentication types requested.
requestedAuth.otp
Y
This is used to inform that OTP authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
requestedAuth.demo
Y
This is used to inform that demographic authentication was performed as part of this request. Default value here is false. Allowed values are true or false.
requestedAuth.bio
Y
This is used to inform that biometric authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
individualId
Y
This represents the ID of resident (VID or UIN). Ex: "9830872690593682".
individualIdType
Y
ID Type used for authentication. Allowed Types of ID - VID, UIN. Default value here is VID.
consentObtained
Y
If consent of residnet is obtained? Default value here is true.
thumbprint
Y
Thumbprint of public key certificate used for encryption of sessionKey. This will be used during key rotation
requestSessionKey
Y
Symmetric Key to be created, and then encrypt the generated Symmetric Key using 'MOSIP Public Key' shared to Partner, and then Base-64-URL encoded. Algorithm used for encryption can be RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.
requestHMAC
Y
SHA-256 hash of request block before encryption. Encryption is done using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request
Y
Request block to be used for authenticating the resident. This is encrypted using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request.otp
N
OTP used for authentication. This is mandatory when requestedAuth.otp is true.
request.timestamp
N
Timestamp when request block was captured.
request.demographics
N
Demographic data of the residnet. This is mandatory when requestedAuth.demo is true.
request.biometrics
N
Biometric data of an Individual which is sent in the response from the Capture API of SBI spec v1.0. Refer to the SBI spec v1.0 specification for complete information. This is mandatory when requestedAuth.bio is true.

Request Body

{
"id": "mosip.identity.auth",
"version": "v1",
"requestTime": "2019-02-15T10:01:57.086+05:30",
"env": "<Target environment>",
"domainUri": "<URI of the authentication server>",
"transactionID": "<Transaction ID of the authentication request>",
"requestedAuth": {
"otp": true,
"demo": false,
"bio": false
},
"consentObtained": true,
"individualId": "9830872690593682",
"individualIdType": "VID",
"thumbprint": "<Thumbprint of the public key certficate used for enryption of sessionKey. This is necessary for key rotaion>",
"requestSessionKey": "<Encrypted and Base64-URL-encoded session key>",
"requestHMAC": "<SHA-256 of request block before encryption and then hash is encrypted using the requestSessionKey>",
//Encrypted with session key and base-64-URL encoded
"request": {
"timestamp": "2019-02-15T10:01:56.086+05:30 - ISO format timestamp",
"otp": "123456",
"demographics": {
"name": [
{
"language": "ara",
"value": "ابراهيم بن علي"
},
{
"language": "fra",
"value": "Ibrahim Ibn Ali"
}
],
"gender": [
{
"language": "ara",
"value": "الذكر"
},
{
"language": "fra",
"value": "mâle"
}
],
"age": "25",
"dob": "25/11/1990",
"fullAddress": [
{
"language": "ara",
"value": "عنوان العينة سطر 1, عنوان العينة سطر 2"
},
{
"language": "fra",
"value": "exemple d'adresse ligne 1, exemple d'adresse ligne 2"
}
]
},
//Same as the response from the Capture API of SBI v1.0. Refer to the [SBI v1.0 specification]() for complete information.
"biometrics": [
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>", // For the first entry assume empty string as previous data block
"sessionKey": "<Encrypted and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumbprint of the certificate that was used for encryption of session key>"
},
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>",
"sessionKey": "<Encrypted and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumbprint of the certificate that was used for encryption of session key>"
}
]
}
}

Responses

Success Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<transaction_id used in request>",
"response": {
"authStatus": true,
"authToken": "<authentication_token>"
},
"errors": null
}
Failed Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<transaction_id used in request>",
"response": {
"authStatus": false,
"authToken": null
},
"errors": [
{
"errorCode": "IDA-MLC-002",
"errorMessage": "Invalid UIN",
"actionMessage": "Please retry with the correct UIN"
}
]
}

Failure Details

For details about the error codes view the section common error codes and messages.

e-KYC Service (Public)

This service details authentication (eKYC auth) that can be used by authentication partners to authenticate an individual and send individual's KYC details as response. Below are various authentication types supported by e-KYC authentication:
  1. 1.
    OTP Authentication - OTP
  2. 2.
    Biometric Authentication - Fingerprint, IRIS and Face

Users of KYC service

  1. 1.
    MISP (MOSIP Infrastructure Service Provider) - MISP's role is limited to infrastructure provisioning and acting as a gate keeper for all KYC requests sent to this service. The MISP is also responsible for policy creation on the MOSIP servers so their partners will follow the set policy.
  2. 2.
    Partners - eKYC-Partners register themselves with MOSIP, under a MISP. KYC requests are captured by eKYC-Partners and sent to MOSIP, via MISP.
  3. 3.
    Partner-Api-Key - Associated against a policy.

POST /idauthentication/v1/kyc/

This request will provide KYC details of an individual, once the individual is successfully authenticated.

Resource URL

https://{base_url}/idauthentication/v1/kyc/:MISP-LicenseKey/:eKYC-Partner-ID/:Partner-Api-Key

Resource Details

Resource Details
Description
Response format
JSON
Requires Authentication
Yes

Request Header Parameters

Name
Required
Description
Authorization
Y
For consent token
Signature
Y
For signature of the authentication request

Request Path Parameters

Name
Required
Description
MISP-LicenseKey
Y
License key provided to the MISP
eKYC-Partner-ID
Y
Partner ID of the authentication partner sending the request
Partner-API-Key
Y
API Key associated to the partner and the policy

Request Body Parameters

Name
Required
Description
id
Y
This represents the API ID. The value here should be "mosip.identity.kyc".
version
Y
This represents the version of the API.
transactionID
Y
This represents the Transaction ID of the request.
requestTime
Y
This represents the time when request was created. Ex: "2019-02-15T10:01:57.086+05:30".
env
Y
This represents the environment. Allowed values are "Staging"
domainUri
Y
This represents the Unique URI per authentication providers. This can be used to federate across multiple providers or countries or unions.
requestedAuth
Y
This represents the authentication types requested.
requestedAuth.otp
Y
This is used to inform that OTP authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
requestedAuth.demo
Y
This is used to inform that demographic authentication was performed as part of this request. Default value here is false. Allowed values are true or false.
requestedAuth.bio
Y
This is used to inform that biometric authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
individualId
Y
This represents the ID of resident (VID or UIN). Ex: "9830872690593682".
individualIdType
Y
ID Type used for authentication. Allowed Types of ID - VID, UIN. Default value here is VID.
consentObtained
Y
If consent of residnet is obtained? Default value here is true.
thumbprint
Y
Thumbprint of public key certificate used for encryption of sessionKey. This will be used during key rotation
requestSessionKey
Y
Symmetric Key to be created, and then encrypt the generated Symmetric Key using 'MOSIP Public Key' shared to Partner, and then Base-64-URL encoded. Algorithm used for encryption can be RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.
requestHMAC
Y
SHA-256 hash of request block before encryption. Encryption is done using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request
Y
Request block to be used for authenticating the resident. This is encrypted using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request.otp
N
OTP used for authentication. This is mandatory when requestedAuth.otp is true.
request.timestamp
N
Timestamp when request block was captured.
request.demographics
N
Demographic data of the residnet. This is mandatory when requestedAuth.demo is true.
request.biometrics
N
Biometric data of an Individual which is sent in the response from the Capture API of SBI spec v1.0. Refer to the SBI spec v1.0 specification for complete information. This is mandatory when requestedAuth.bio is true.
secondaryLangCode
N
Secondary language code. If specifed, the KYC response will contain KYC data for the give secondary language code also along with primary language data. Otherwise, the response will contain only primary language data.

Request Body

{
"id": "mosip.identity.kyc",
"version": "v1",
"requestTime": "2019-02-15T10:01:57.086+05:30",
"env": "<Target environment>",
"domainUri": "<URI of the authentication server>",
"transactionID": "<Transaction ID of the authentication request>",
"requestedAuth": {
"otp": true,
"demo": false,
"bio": true
},
"consentObtained": true,
"individualId": "9830872690593682",
"individualIdType": "VID",
"thumbprint": "<SHA256 representation of thumb-print of the MOSIP public key certificate used for encryption of sessionKey>",
"requestSessionKey": "<Encrypted using MOSIP public key and base64-URL-encoded session key>",
"requestHMAC": "<SHA-256 of request block before encryption and then hash is encrypted using the requestSessionKey>",
//request section is first encrypted with the session key and then base64-URL-encoded
"request": {
"timestamp": "2019-02-15T10:01:56.086+05:30 - ISO format time-stamp",
"otp": "123456",
//biometric section is same as the response from Capture API mentioned in [SBIv1.0 specification]()
"biometrics": [
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>", // For the first entry assume empty string as previous data block
"sessionKey": "<Encrypted with MOSIP public key and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumb-print of the MOSIP public key that was used for encryption of session key>"
},
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>",
"sessionKey": "<Encrypted and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumb-print of the MOSIP public key that was used for encryption of session key>"
}
]
},
"secondaryLangCode": "ara"
}

Responses

Success Response
Response Code : 200 (OK)
{
"id": "mosip.identity.kyc",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<Transaction ID received in request>",
"response": {
"kycStatus": true,
"authResponseToken": "<Authentication response token>",
//Encrypted KYC info using Partner's public key and base64-URL-encoded
"identity": {
"name": [
{
"language": "ara",
"value": "ابراهيم"
},
{
"language": "fra",
"value": "Ibrahim"
}
],
"dob": "25/11/1990",
"gender": [
{
"language": "ara",
"value": "الذكر"
}
],
"phoneNumber": "+212-5398-12345",
"emailId": "[email protected]",
"addressLine1": [
{
"language": "ara",
"value": "عنوان العينة سطر 1"
},
{
"language": "fra",
"value": "exemple d'adresse ligne 1"
}
],
"addressLine2": [
{
"language": "ara",
"value": "عنوان العينة سطر 2"
},
{
"language": "fra",
"value": "exemple d'adresse ligne 2"
}
],
"addressLine3": [
{
"language": "ara",
"value": "عنوان العينة سطر 3"
},
{
"language": "fra",
"value": "exemple d'adresse ligne 3"
}
]
},
"thumbnail": "<SHA256 representation of thumb-print of the Partner's public key used for encryption of identity block>"
},
"errors": null
}
Failed Response
Response Code : 200 (OK)
{
"id": "mosip.identity.kyc",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<Transaction ID received in request>",
"response": {
"kycStatus": false,
"authResponseToken": null,
"identity": null,
"thumbnail": null
},
"errors": [
{
"errorCode": "IDA-MLC-002",
"errorMessage": "Invalid UIN",
"actionMessage": "Please retry with the correct UIN"
}
]
}

Failure Details

For details about the error codes view the section common error codes and message.

OTP Request Service (Public)

This service enables authentication partners to request for an OTP for an individual. The OTP will be send via message or email as requested to the individual. This OTP can then be used to authenticate the individual using authentication or eKYC service.

Users of OTP Request service

  1. 1.
    MISP (MOSIP Infrastructure Service Provider) - MISP acts as a gate keeper for any OTP requests sent to this service. MISP is also responsible for the policy creation on the MOSIP servers so their partners will follow the set policy.
  2. 2.
    Partners - Auth-Partners and eKYC-Partners can send OTP Request to MOSIP on behalf of the individual for Authentication and eKYC requests respectively, via MISP.
  3. 3.
    Partner-Api-Key - Associated against a policy.

POST /idauthentication/v1/otp/

This request will send an OTP to the individual whoes UIN/VID is entered.

Resource URL

https://{base_url}/idauthentication/v1/otp/:MISP-LicenseKey/:Partner-ID/:Partner-Api-Key

Resource details

Resource Details
Description
Response format
JSON
Requires Authentication
Yes

Request Header Parameters

Name
Required
Description
Authorization
Y
This is for sending the consent token
Signature
Y
This is for sending the signature of the authentication request

Request Body Parameters

Name
Required
Description
id
Y
This represents the API ID. The value here would be "mosip.identity.otp".
version
Y
This represents the API version.
transactionID
Y
Transaction ID of the request. Ex: "1234567890".
requestTime
Y
Time when request was captured. Ex:"2019-02-15T10:01:57.086+05:30"
env
Y
Target environment. Allowed values are "Staging", "Developer", "Pre-Production" or "Production".
domainUri
Y
Unique URI per auth providers. This can be used to federate across multiple providers or countries or unions.
individualId
Y
ID of resident (VID or UIN). Ex: "9830872690593682".
individualIdType
Y
ID Type of resident used. Allowed Types of ID - VID, UIN. Default Value here is VID.
otpChannel
Y
OTP channel for sending OTP request. Allowed OTP Channels - EMAIL, PHONE.

Request Body

{
"id": "mosip.identity.otp",
"version": "v1",
"requestTime": "2019-02-15T07:22:57.086+05:30",
"env": "<Target environment>",
"domainUri": "<URI of the authentication server>",
"transactionID": "<Transaction ID of the authentication request>",
"individualId": "9830872690593682",
"individualIdType": "VID",
"otpChannel": [
"EMAIL",
"PHONE"
]
}

Responses

Success Response
Response Code : 200 (OK)
{
"id": "mosip.identity.otp",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<Transaction ID of the authentication request>",
"response": {
"maskedMobile": "XXXXXXX123",
"maskedEmail": "[email protected]"
},
"errors": null
}
Failed Response
Response Code : 200 (OK)
{
"id": "mosip.identity.otp",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "<Transaction ID of the authentication request>",
"response": null,
"errors": [
{
"errorCode": "IDA-MLC-003",
"errorMessage": "Invalid VID",
"actionMessage": "Please retry with correct VID"
}
]
}

Failure Details

Error Code
Error Message
Description
Action Message
IDA-MLC-001
Request to be received at MOSIP within<x> hrs/min
Invalid Time stamp
Please send the request within <x> hrs/min
IDA-MLC-002
Invalid UIN
Invalid UIN
Please retry with the correct UIN.
IDA-MLC-003
UIN has been deactivated
UIN Deactivated
Your UIN status is not active.
IDA-MLC-004
Invalid VID
Invalid VID
Please retry with correct VID.
IDA-MLC-005
%s VID
Expired,Used,Revoked VID
Please regenerate VID and try again
IDA-MLC-006
Missing Input parameter- <attribute> Example: Missing Input parameter- version
Missing Input parameter- attribute - all the mandatory attributes
IDA-MLC-007
Request could not be processed. Please try again
Could not process request/Unknown error; Invalid Auth Request; Unable to encrypt eKYC response
IDA-MLC-009
Invalid Input parameter- attribute
Invalid Input parameter- attribute
IDA-MLC-010
VID has been deactivated
VID corresponding to a deactivated UIN
IDA-MLC-014
<Notification Channel> not registered. Individual has to register and try again
<Notification Channel> not Registered (Phone/e-mail/both)
Please register your <Notification Channel> and try again
IDA-MLC-015
Identity Type - <Identity Type> not configured for the country
ID Type (UIN/VID) not supported for a country
IDA-MLC-017
Invalid UserID
Invalid UserID
IDA-MLC-018
%s not available in database
UIN,VID, User ID not available in database
IDA-MPA-004
MOSIP Public key expired.
MOSIP Public key expired
Please reinitiate the request with updated public key
IDA-MPA-005
OTP Request Usage not allowed as per policy
OTP Trigger Usage not allowed as per policy
IDA-MPA-007
License key does not belong to a registered MISP
License key does not belong to a registered MISP/ License key invalid
IDA-MPA-008
License key of MISP has expired
License key expired
IDA-MPA-009
Partner is not registered
PartnerID Invalid
IDA-MPA-010
MISP and Partner not mapped
MISP and Partner not
IDA-MPA-011
License key of MISP is suspended
License key status of MISP is suspended
IDA-MPA-012
Partner is deactivated
PartnerID is not active
IDA-MPA-014
Partner is not assigned with any policy
PartnerID is not mapped to a policy
IDA-MPA-017
License key of MISP is blocked
License key status of MISP is blocked
IDA-OTA-001
In numerous OTP requests received
OTP Flooding error
IDA-OTA-002
Could not generate/send OTP
Could not generate/send OTP
IDA-OTA-006
UIN is locked for OTP generation. Please try again later
Try to generate OTP for a frozen Account
IDA-OTA-008
OTP Notification Channel not provided.
No OTP Channel is provided in the input
IDA-OTA-009
<Notification Channel> not configured for the country
<Notification Channel> not configured (Phone/e-mail/both)

Authentication Service (Internal)

This service details authentication (yes/no) that can be used by MOSIP modules to authenticate an individual using UserID/VID/UIN. Below are various authentication types supported by this service - Biometric based - Fingerprint, IRIS and Face.

Users of Internal Authentication service

  1. 1.
    Registration Client - Registration Client can authenticate biometrics of Operator or Supervisor while on-boarding them.
  2. 2.
    Registration Processor - Registration Processor can authenticate biometrics of Operator or Supervisor while processing registration packets.

POST /idauthentication/v1/internal/auth

This request will authenticate an Operator/Supervisor using Biometric authentication.

Resource URL

https://{base_url}/idauthentication/v1/internal/auth

Resource details

Resource Details
Description
Response format
JSON
Requires Authentication
Yes

Request Header Parameters

Name
Required
Description
Authorization
Y
This is for sending the consent token
Signature
Y
This is for sending the signature of the authentication request

Request Body Parameters

Name
Required
Description
id
Y
This represents the API ID. The value here should be "mosip.identity.auth.internal".
version
Y
This represents the version of the API.
transactionID
Y
This represnets the Transaction ID of the request.
requestTime
Y
This represents the time when request was created. Ex: "2019-02-15T10:01:57.086+05:30".
env
Y
This represents the enviornment. Allowed values are "Staging"
domainUri
Y
This represents the Unique URI per auth providers. This can be used to federate across multiple providers or countries or unions.
requestedAuth
Y
This represents the authentication types requested.
requestedAuth.otp
Y
This is used to inform that OTP authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
requestedAuth.demo
Y
This is used to inform that demographic authentication was performed as part of this request. Default value here is false. Allowed values are true or false.
requestedAuth.bio
Y
This is used to inform that biometric authentication was performed as part of this request. Default Value here is false. Allowed values are true or false.
individualId
Y
This represents the ID of resident (VID or UIN). Ex: "9830872690593682".
individualIdType
Y
ID Type used for authentication. Allowed Types of ID - VID, UIN. Default value here is VID.
consentObtained
Y
If consent of residnet is obtained? Default value here is true.
thumbprint
Y
Thumbprint of public key certificate used for encryption of sessionKey. This will be used during key rotation
requestSessionKey
Y
Symmetric Key to be created, and then encrypt the generated Symmetric Key using 'MOSIP Public Key' shared to Partner, and then Base-64-URL encoded. Algorithm used for encryption can be RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.
requestHMAC
Y
SHA-256 hash of request block before encryption. Encryption is done using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request
Y
Request block to be used for authenticating the resident. This is encrypted using 'requestSessionKey' and then base64URL encoded. Algorithm used for encryption can be AES/GCM/PKCS5Padding.
request.otp
N
OTP used for authentication. This is mandatory when requestedAuth.otp is true.
request.timestamp
N
Timestamp when request block was captured.
request.demographics
N
Demographic data of the residnet. This is mandatory when requestedAuth.demo is true.
request.biometrics
N
Biometric data of an Individual which is sent in the response from the Capture API of SBI spec v1.0. Refer to the SBI spec v1.0 specification for complete information. This is mandatory when requestedAuth.bio is true.

Request Body

{
"id": "mosip.identity.auth.internal",
"version": "v1",
"requestTime": "2019-02-15T10:01:57.086+05:30",
"env": "<Target environment>",
"domainUri": "<URI of the authentication server>",
"transactionID": "<Transaction ID of the authentication request>",
"requestedAuth": {
"otp": true,
"demo": false,
"bio": false
},
"consentObtained": true,
"individualId": "9830872690593682",
"individualIdType": "VID",
"thumbprint": "<Thumbprint of the public key certficate used for enryption of sessionKey. This is necessary for key rotaion>",
"requestSessionKey": "<Encrypted and Base64-URL-encoded session key>",
"requestHMAC": "<SHA-256 of request block before encryption and then hash is encrypted using the requestSessionKey>",
//Encrypted with session key and base-64-URL encoded
"request": {
"timestamp": "2019-02-15T10:01:56.086+05:30 - ISO format timestamp",
"otp": "123456",
"demographics": {
"name": [
{
"language": "ara",
"value": "ابراهيم بن علي"
},
{
"language": "fra",
"value": "Ibrahim Ibn Ali"
}
],
"gender": [
{
"language": "ara",
"value": "الذكر"
},
{
"language": "fra",
"value": "mâle"
}
],
"age": "25",
"dob": "25/11/1990",
"fullAddress": [
{
"language": "ara",
"value": "عنوان العينة سطر 1, عنوان العينة سطر 2"
},
{
"language": "fra",
"value": "exemple d'adresse ligne 1, exemple d'adresse ligne 2"
}
]
},
//Same as the response from the Capture API of SBI v1.0. Refer to the [SBI v1.0 specification]() for complete information.
"biometrics": [
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>", // For the first entry assume empty string as previous data block
"sessionKey": "<Encrypted and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumbprint of the certificate that was used for encryption of session key>"
},
{
"specVersion" : "<SBI specification version>",
"data": "<JWS signature format of data containing encrypted biometrics and device details>",
"hash": "<SHA-256 hash of (SHA-256 hash of previous data block in hex format + SHA-256 of current data block before encrypting in hex format) in hex format>",
"sessionKey": "<Encrypted and base64-URL-encoded session key>",
"thumbprint": "<SHA256 representation of thumbprint of the certificate that was used for encryption of session key>"
}
]
}
}

Responses

Success Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth.internal",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "1234567890",
"response": {
"authStatus": true
},
"errors": null
}
Failed Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth.internal",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"transactionID": "1234567890",
"response": {
"authStatus": false
},
"errors": [
{
"errorCode": "IDA-MLC-009",
"errorMessage": "Invalid UserId",
"actionMessage": "Please retry with the correct UserId"
}
]
}

Failure Details

Error Code
Error Message
Description
Action Message
IDA-BIA-001
Biometric data – <Biometric Attribute> did not match
Finger,Iris,Face Mismatch
Please give your biometrics again.
IDA-BIA-002
Duplicate fingers in request.
Duplicate fingers
Please try again with distinct fingers
IDA-BIA-003
Number of Fingers should not exceed 10.
Fingers exceeding 10
IDA-BIA-006
Biometric data <Biometric Attribute> not available in database.
Missing biometric data in MOSIP database
Your Biometric data is not available in MOSIP
IDA-BIA-007
Duplicate Irises in request.
Duplicate Irises used
Please try again with distinct Irises
IDA-BIA-008
Number of Iris should not exceed 2.
Irises exceeding 2
IDA-BIA-009
Number of Face records should not exceed 1.
Face exceeding 1
IDA-MLC-001
Request to be received at MOSIP within<x> hrs/min
Invalid Time stamp
Please send the request within <x> hrs/min
IDA-MLC-002
Invalid UIN
Invalid UIN
Please retry with the correct UIN.
IDA-MLC-003
UIN has been deactivated
UIN Deactivated
Your UIN status is not active.
IDA-MLC-006
Missing Input parameter- <attribute> Example: Missing Input parameter- version
Missing Input parameter- attribute - all the mandatory attributes
IDA-MLC-007
Request could not be processed. Please try again
Could not process request/Unknown error; Invalid Auth Request; Unable to encrypt eKYC response
IDA-MLC-008
No authentication type selected
No authentication type selected in the request
IDA-MLC-009
Invalid Input parameter- attribute
Invalid Input parameter- attribute
IDA-MLC-011
Unsupported Authentication Type - <Auth Type> - <SubType> if applicable
Auth Type not supported for a country
Please use other Authentication Types in the request
IDA-MLC-012
Individual's Consent is not available
Invalid resident consent for eKYC/Auth
IDA-MLC-013
Missing <authtype> auth attribute
Missing authtype parameter – when <auth-type> = ‘True’ and corresponding auth attribute missing (OTP,Demo and Bio)
IDA-MLC-014
<Notification Channel> not registered. Individual has to register and try again
<Notification Channel> not Registered (Phone/e-mail/both)
Please register your <Notification Channel> and try again
IDA-MLC-015
Identity Type - <Identity Type> not configured for the country
ID Type (UIN/USERID) not supported for a country
IDA-MLC-017
Invalid UserID
Invalid UserID
IDA-MLC-018
%s not available in database
UIN, User ID not available in database
IDA-MPA-003
Unable to decrypt Request.
Invalid encryption of session key/request
IDA-MPA-004
MOSIP Public key expired.
MOSIP Public key expired
Please reinitiate the request with updated public key

Authentication Transactions Service (Internal)

Authentication Transactions Service can be used by Resident Services to retrieve authentication history of an Individual initiated by Partners. Authentications done by MOSIP's internal modules for any verification will not be returned.

Users of Authentication Transactions Service

Resident Services - Resident Services will send UIN or VID to retrieve all authentication transactions of an Individual, that are initiated by Partners.

GET /idauthentication/v1/internal/authTransactions/individualIdType/

This request will retrieve authentication transactions for the given UIN/VID, alongwith pageStart and pageFetch parameters.

Resource URL

https://{base_url}/idauthentication/v1/internal/authTransactions/individualIdType/:IDType/individualId/:ID?pageStart=1&pageFetch=10

Resource Details

Resource Details
Description
Response format
JSON
Requires Authentication
Yes

Request Path Parameters

Name
Required
Description
ID Type
Y
Allowed values here can be UIN or VID.
ID
Y
This is the value of ID Type - UIN or VID.

Request Query Parameters

The authentication transactions can be queried using this REST service for certain count of transactions which can be retrieved for given pageStart number with pageFetch. The default pageStart value is 1. The default pageFetch value is 10. This default pageFetch value will be taken into account only if the pageStart is provided. If both pageStart and pageFetch values are not provided, all the authentication transactions for the UIN/VID are returned in the response.
Name
Required
Description
pageStart
N
The page number to start. Default value here is "1".
pageFetch
N
The number of entries per page. Default value here is "10".

Responses

Success Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth.transactions.read",
"responseTime": "2019-07-11T07:30:59.383",
"version": "v1",
"errors": [],
"response": {
"authTransactions": [
{
"transactionID": "1234567890",
"requestdatetime": "2019-07-10T07:28:59.383",
"authtypeCode": "FINGERPRINT-AUTH",
"statusCode": "Y",
"statusComment": "Finger Authentication Success",
"referenceIdType": "UIN",
"entityName": ""
},
{
"transactionID": "1234567891",
"requestdatetime": "2019-07-11T07:29:59.383",
"authtypeCode": "OTP-REQUEST",
"statusCode": "F",
"statusComment": "OTP Authentication Failed",
"referenceIdType": "UIN",
"entityName": ""
}
]
}
}
Failed Response
Response Code : 200 (OK)
{
"id": "mosip.identity.auth.transactions.read",
"version": "v1",
"responseTime": "2019-02-15T07:23:19.590+05:30",
"errors": [
{
"errorCode": "IDA-MLC-002",
"errorMessage": "Invalid UIN",
"actionMessage": "Please retry with the correct UIN"
}
]
}

Failure Details

Error Code
Error Message
Description
Action Message
IDA-MLC-001
Request to be received at MOSIP within<x> hrs/min
Invalid Time stamp
Please send the request within <x> hrs/min
IDA-MLC-002
Invalid UIN
Invalid UIN
Please retry with the correct UIN.
IDA-MLC-003
UIN has been deactivated
UIN Deactivated
Your UIN status is not active.
<