Skip to main content

Participant registry

Update certificate (v2, no passcode)

Replaces a participant's public encryption certificate by participantId without passcode validation; the same schema is echoed back on success.

POST/v2/update/cert

### Business purpose

Encryption keys are recommended to be rotated once a year, and a compromised key must be replaced immediately. The passcode-gated /v2/participant/update is the safer general route, but it needs a person with the registered phone and a 24-hour confirmation step. This endpoint exists for certificate-only updates without that validation, so an organisation can publish a new public certificate quickly. Only the certificate changes; the endpoint URL is untouched.

### When to use

Use it for scheduled annual rotation or emergency replacement of the certificate when passcode validation is not wanted. The production URL is https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/update/cert. To change the callback URL as well, use /v2/participant/update instead. It is the last item of the certificates checklist alongside the v2 participant update. Synchronous JSON; no workflow or x-hcx-status codes.

### Preconditions

- Bearer token from /get/session in bearer_auth with the Bearer prefix; Accept and Content-Type: application/json. - UpdateCertV2 body: participantId and certificate, both mandatory; the certificate must be Base64-encoded (the NHA steps produce a self-signed X.509 RSA certificate, then Base64-encode the whole PEM text). - The matching new private key, in PKCS8 form, is already deployed on the callback host. - Note the camelCase field participantId, unlike participant_code (v1) and participantcode (v2 update).

### Postconditions

HTTP 200 with the UpdateCertV2 schema echoed back (participantId and certificate). The registry's encryption certificate for that participant is replaced, so /fetch/certs returns the new one from the next call; counterparties may serve a cached copy for up to 24 hours. No transactionid is issued and no /update/validate step follows. No callback. 400, 404 and 500 use the ErrorResponse envelope.

### Common mistakes

- Sending the raw PEM rather than the Base64-encoded certificate, which the validation explicitly requires. - Using participant_code, participantcode or encryptioncert; this schema is participantId and certificate. - Publishing the new certificate before the new private key is live on the callback host, so inbound callbacks fail to decrypt (PAYR-1001 on the counterparty side, undecryptable payloads on yours). - Discarding the old private key immediately, even though counterparties can hold the old certificate for 24 hours. - Trying to change the endpoint URL here; only the certificate is accepted.

### Best practices

- Rotate in two phases: deploy the new PKCS8 private key, publish the certificate, and keep the old key for at least 24 hours. - Generate a 2048-bit RSA key and a 365-day self-signed X.509 certificate so the validity matches the annual rotation recommendation. - Verify with /participant/search or a /fetch/certs call against your own code that the new certificate is served. - Restrict who can call this endpoint inside your organisation, since it replaces the key that protects all inbound health data without a passcode. - Notify the ecosystem promptly if rotation is due to suspected compromise, as the protocol expects.

### Related scenario

A hospital's security audit finds its NHCX private key was copied to a shared drive. The team generates a new 2048-bit RSA key pair and 365-day self-signed certificate, deploys the PKCS8 private key to the callback host and Base64-encodes the certificate. With a Bearer token they call /v2/update/cert with participantId XXXXX7583@hcx and the certificate; the registry echoes the schema back. They keep the old key available for one day so payers still holding the cached certificate can be decrypted, then destroy it. The next /v1/preauth/on_submit from the payer, encrypted against the new certificate, decrypts cleanly.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

Body

participantIdstring
certificatestring

Responses

200

HTTP 200 with the UpdateCertV2 schema echoed back (participantId and certificate).