Technical Details
Last updated
Was this helpful?
Last updated
Was this helpful?
This section outlines the technical requirements for integrating a Civil Registration and Vital Statistics (CRVS) system with MOSIP, applicable to any country implementation. It covers the necessary prerequisites and API specifications to facilitate a seamless and secure connection between the two systems, enabling smooth data exchange and processing of birth registration requests. Depending on the country's implementation model and agreements, these steps may be carried out by the System Integrator (SI) or the CRVS team.
To initiate any registration request, the country must define an ID schema based on the specific requirements for CRVS integration. The sample ID schema can be referred to and should be customized to include all required fields for packet generation per the country’s requirements. This schema governs the structure of the data submitted to MOSIP for processing and storage in the Identity Repository.
For comprehensive guidance on defining and customizing the ID schema in MOSIP, please refer to the .
As part of the integration approach, two specific API’s are exposed:
Create a packet API from the MOSIP packet manager module to create a packet
Trigger the API from the registration processor module to process the packet.
allowing external systems (in this case, CRVS) to use these APIs to initiate requests.
To facilitate this, the external system must be assigned a specific new client ID and secret, ensuring secure and authenticated communication. Additionally, a new, specific role should be created for the external user, which will be associated with the API request in subsequent calls for packet creation and processing.
This role helps MOSIP validate and verify that the request is coming from an authorized and authentic source, ensuring secure and accurate handling of the registration process. By associating the role with the API request, MOSIP can properly authenticate the external system and manage permissions for the request flow.
Read on to learn more about the specific steps involved
Create the Client
Log in to Keycloak Admin Console
Access the keycloak admin console.
Ensure you have the necessary administrative privileges to create clients.
Select Your Realm
If you are not already in the desired realm, switch to it from the top-left drop-down menu. The realm should be the one where you want to create the client.
Create a New Client
In the left-hand menu, go to Clients and click on Create.
Enter the Client Details
Client ID: Enter mosip-crvs1-client as the client ID (or a relevant name based on your deployment).
Client Protocol: Select openid-connect.
Root URL: Leave this field blank or enter the URL if required.
Save the Client
After entering the necessary details, click Save to create the client.
Once the client is created, please update the properties in the locations below:
Configuring the Client
Access the Settings Tab
After creating the client, navigate to the Settings tab.
Configure Client Settings
Access Type: Set this to confidential if you intend to use client credentials for authentication.
Service Accounts Enabled: Turn this option ON if you are using client credentials flow for secure communication.
Valid Redirect URIs: Enter * (or specify specific URLs if known and necessary).
Save the Changes
Once the configuration is complete, click Save to apply the changes.
Generate and note the Secret key
Navigate to the Credentials tab.
If you selected the confidential access type, keycloak will generate a Secret Key. Note this secret as it will be used for authentication in subsequent API calls.
Creating the Role
Go to the Roles Section
In the Keycloak Admin Console, under your realm, navigate to Roles.
Create a New Role
Click on Add Role.
Enter the following details:
Role Name: ONLINE_REGISTRATION_CLIENT
Click Save to create the role.
Assign the Role to the Client
Go back to the Clients section and select the client mosip-crvs1-client that you previously created.
Navigate to Service Account Roles
Under the Service Account Roles tab (this tab is visible only if Service Accounts Enabled is turned on), click on Add Role.
Select the Role
From the Client Roles dropdown, select either realm-management or your specific desired client role (if the role is specific to a client).
Add the ONLINE_REGISTRATION_CLIENT role to the selected client.
Once the role is created and mapped to the client ID. As a follow-up step, below keycloak API is to be called to authenticate the CRVS associated with the new role. In the response of the API, there is an access token returned in the response header. This is the access token that should be used when initiating any request using the packet manager API. Authenticate Endpoint: {domainname}/v1/authmanager/authenticate/clientidsecretkey
Method: POST
API Request Structure:
In the API above, the fields Client ID and Secret key are the values created in the previous steps, as mentioned above. Once the authentication is successful, in the response header, we will receive an access token, which is to be noted and used for the subsequent packet manager API request.
To process the request coming from CRVS, a default officer is to be registered and assigned to the CRVS. The officer is to be added from keycloak by the admin.
Log in to Keycloak
Open the Keycloak admin portal.
Log in using your admin credentials.
Navigate to the Users Section
In the left-hand menu, click on Users.
Add a New User
Click on the Add user button to create a new user.
Fill in the required fields under the details tab:
Username: Enter a unique username for the officer (this will become the Officer ID).
First Name: Enter the officer's first name.
Last Name: Enter the officer's last name.
Set Temporary Password
Under the Credentials tab, set the password for the officer.
Toggle Temporary to Off to disable the "temporary password" feature.
Click Set Password.
Enable the User
Under the User Enabled section, ensure that the user is enabled.
Click Save to create the user.
Assign Roles to the User
Navigate to the Role Mappings tab.
Under Available Roles, select the role Registration_officer.
Click the Add selected button to assign the role.
Finalize the Officer Creation
After saving, the officer's username from step 3 will serve as the Officer ID.
This Officer ID will be used in the subsequent create packet API request. Ensure you pass this ID correctly in the request.
Fetching the Centre ID As of now, there is no direct support for fetching the specific centre ID in MOSIP. To retrieve the Centre ID, use the API below to get a list of all centres in the system. From this list, manually search for the Centre ID associated with the newly created centre for CRVS. The “id“ attribute in the response will be the centre ID.
Get List of All Centres Endpoint: {domain}/v1/admin/masterdata/registrationcenters
Method: GET Once the Centre ID is identified, ensure it is saved securely for future reference. This Centre ID will be required in subsequent interactions with the CRVS system for processing requests.
A unique default machine will be assigned to the CRVS to process requests. This machine can be created through the Admin Portal.
Before creating a new machine, it is required that a public key is fetched using the below API. The public key received in the response of this API is to be used as the public key & signing public key, while adding the details in the admin portal, to create and onboard the machine.
URL: {domain}/v1/keymanager/tpmsigning/publickey
Method: POST
API Request Structure:
Sample Response:
Fetching the Machine ID
As of now, there is no direct support for fetching the specific machine ID in MOSIP. To retrieve the machine ID, use the API below to get a list of all centres in the system. From this list, manually search for the machine ID associated with the newly created centre for CRVS. The “id“ attribute in the response will be the machine ID.
Get a List of All Machine Endpoints: {domain}/v1/masterdata/machines
Method: GET
Once the Machine ID is identified, ensure it is saved securely for future reference. This Machine ID will be required in subsequent interactions with the CRVS system for processing requests.
Once the officer, centre, and machine are created for CRVS, the next step is to map the user to the centre. This ensures the user is properly associated with the correct zone and centre for their operations.
Log in to Admin UI
Log in to the Admin UI using the admin user created in Keycloak if it is a fresh environment.
Map Zone to User
Navigate to Resources → User Zone Mapping → Map Zone.
Select the username for which the zone is to be mapped.
Choose the appropriate zone from the dropdown.
Click Save.
Refer to the accompanying images for further guidance.
Activate the User
After mapping the zone, activate the user.
Map Centre to User
Navigate to Resources → User Centre Mapping.
Select the username for which the centre needs to be mapped.
Choose the appropriate centre from the dropdown.
Click Save.
Activate the user, as outlined in Step 3.
The Application ID (AID) refers to the unique identifier assigned to track the packet that is being processed for events such as birth or death registration. It can be used by MOSIP or CRVS to track the progress and status of the specific event.
AID Structure(Recommended):
Centre ID (First 5 digits): The first 5 digits of the RID represent the Centre ID.
Machine ID (Next 5 digits): The next 5 digits of the RID represent the Machine ID.
Random Sequence (next N digits): The next N digits can be a randomly generated sequence based on the length that the country wants to use for the RID.
Example of AID:
For the AID 10001100771006920220128223618The breakdown is as follows:
Centre ID: 10001 (First 5 digits)
Machine ID: 10077 (Next 5 digits)
Random Sequence: 1006920220128223618 (Remaining 16 digits)
The AID format mentioned above is the recommendation to be followed, but not mandatory. CRVS can generate the AID in any specified format as per their requirement and include it in the Create Packet API Request to ensure proper packet identification and mapping.
Once all the above pre-requisites are in place, the next step is to initiate a request(birth/death/update) by calling the create packet API of MOSIP’s packet manager module. API structure, required fields, and other details are mentioned further in this document.
Create Packet Endpoint: {domain}/commons/v1/packetmanager/createPacket
Method: PUT
API request Structure:
source: Specifies the source of the registration request. This will be the same for any request that comes to MOSIP for birth or death.
process: Identifies the specific process for the registration.
CRVS_NEW - When initiating an infant birth request
CRVS_DEATH - When initiating a death registration request
idThe unique identifier for the registration request(AID).
ref_id: Combination of centre ID and machine ID.
Ex - “centerid_machineid”
schema_versionThe version of the ID schema that the country is using in production.
Field object:
fullName: The full name of the individual.
dateOfBirth: The date of birth of the individual.
gender: Gender of the individual.
addressLine1: First line of the address.
addressLine2: Second line of the address.
city: City of residence.
state: State of residence.
postalCode: Postal code of the address.
email: Email address.
phone: Contact phone number.
zone: Geographic zone.
region: Region of the address.
province: Province of residence.
Additional fields
Birth registration field:
introducerInfoToken: Introducer’s eSignet user info jwt token, to be passed when sending a request for the birth registration
Death registration field:
deceasedInformer: Informant’s eSignet user info jwt token, to be passed when sending a request for the death registration
deceasedDeclarationDate: The date on which the individual was declared deceased.
declaredAsDeceased: A flag indicating that the individual has been officially marked as deceased.
typeOfDeath: Specifies the nature of the death, such as natural or jurisdictional.
MetaInfo Object (Center and Operator Information):
centerId: Unique identifier for the centre where the registration is processed.
machineId: Unique identifier for the machine used for registration.
operationsData: Contains fields such as officer ID, officer password, supervisor ID, etc.
registration_type: This is the value same as the process field for birth(CRVS_NEW) or death(CRVS_DEATH).
centerId, machineId, officerId must be provided along with any additional relevant operational information for the request to be processed.
Audit Object:
uuid: Unique uuid to be sent with any request coming from CRVS.
Please add the values for the other fields in the audit object as per the details of the machine and the person who is registering the request from the CRVS.
It is required that at least one attribute in the audit object is populated with valid data before making the request.
schemaJson: JSON schema (in stringified format) used by the country
Sample Response:
9. Trigger API (Registration Processor Module)
In MOSIP, after a packet is created, it is processed for validations and verification of the information in the Registration Processor. Inside the Registration Processor, each packet follows a specific workflow defined by the Camel route.
auth.server.admin.allowed.audience In the .
auth.server.admin.allowed.audience In the .
A unique default centre will be assigned to the CRVS to process requests. This centre can be created through the Admin Portal. For detailed instructions on how to create a centre, refer to the
For detailed instructions on how to create a machine, refer to the
For the integration with CRVS, the newly created packet is uploaded to the Object Store. To pick up this new packet and trigger the processing, we have developed a new API. This API ensures to trigger the appropriate workflow is triggered for further processing of the registration packet. For this integration, the camel route workflow to be executed is determined by the values provided for the source and process. API Documentation: