Skip to main content

Every NHCX call returns 401

Every call fails with 401, often with the message Sender is not authorized to execute the operation. When every endpoint fails the same way, the fault is your token or the header carrying it. It is not any one call.

In short​

  • An expired token is the usual cause. Fetch a new one and retry the failing call once.
  • The header value is Bearer, a space, then the token.
  • Send the token in bearer_auth. NHCX reads bearer_auth, not Authorization.
  • A sandbox token never works against a production host.

Prerequisites​

  • More than one endpoint is failing. If one call fails while others succeed, read that call's own error instead.
  • You have the full response body, not only the status code.

Work through these in order​

  1. Has the token expired? An expired token returns this message. A token lasts 1200 seconds (20 minutes) from the moment it arrives, so a token older than that has expired. Fetch a new token and retry the failing call once. A retry with the old token fails the same way.
  2. Does the value start with Bearer ? The header value is the word Bearer, a space, then the token. A bare token returns 401.
  3. Is the token in the header the call reads? Every NHCX call reads the token from bearer_auth, not Authorization.
  4. Are the token and the host from the same environment? A sandbox token does not work against a production host, or the reverse. Compare the host that issued the token with the host of the failing call. Base URLs lists both.
  5. Is the token call itself healthy? If minting a token fails, check the credentials and the body. The session address needs grantType set to client_credentials. Session Token has the call.

What you see when it works​

A call that returned 401 now returns its normal response. It keeps doing so across several calls, over more than 20 minutes, which is longer than one token lasts. One success can be a token that happened to be fresh, so confirm again after the next refresh.

When it goes wrong​

A 401 on linking or de-linking a policy, while other calls work, is a different fault. The token must come from the client ID that created the payer or TPA named in the link. Run the linking job under those credentials.

If all five checks pass and calls still return 401, the credentials may have been revoked or reissued. Write to hcx.integration@nha.gov.in with the call, its time and the full response body. Never send the token or the client secret.

Next steps​

Last updated on