Network & Protocol

Every UHI service uses the same protocol envelope. This page describes the parts that all services share. Read this page before you read a service page.

The asynchronous pattern

UHI API calls are asynchronous. A request never returns business data in the HTTP response.

1. The sender posts a request, for example search.
2. The receiver returns an HTTP 200 ACK at once. The ACK confirms receipt only.
3. The receiver processes the request.
4. The receiver posts the result to the callback endpoint of the sender, for example on_search. The Gateway delivers callbacks to the consumer_uri of the EUA.

{
  "message": {
    "ack": {
      "status": "ACK"
    }
  },
  "error": {}
}

A receiver that rejects a request returns a NACK with an error object:

The context block

Every UHI API call carries a context block. The block routes and correlates the message.

Authentication and signatures

You must sign every UHI API call. The network uses 2 cryptographic components:

Authorization: {"headers":"(created) (expires) digest","algorithm":"ed25519","keyId":"<subscriber-id>|<key-id>|ed25519","created":"<epoch>","expires":"<epoch>","signature":"<base64-sig>"}

Follow these steps to prepare your keys:

Gateway endpoints

The NHA develops and operates the UHI Gateway. You do not build these endpoints. You call them, or you receive calls from them.

Network registry lookup

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/networkregistry/lookup" \
-H "Content-Type: application/json" \
-d '{
  "subscriber_id": "nha.eua",
  "type": "EUA",
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:08752",
  "pub_key_id": "nha.eua.k1"
}'

Sandbox environment

Communication models

UHI uses 2 communication models. Each service page states which model applies to each call.