Skip to main content

Other

Swagger UI configuration

Returns the Swagger UI display configuration for the status service; consumed by Swagger UI, not by integrations.

GET/swagger-resources/configuration/ui

### Business purpose

Swagger UI reads this endpoint to learn how the service wants its documentation rendered (for example, expansion and deep-linking settings). It supports the interactive exploration of the status service's /v1/status operation and has no role in claim settlement, routing or security. The endpoint index describes it as the Swagger UI configuration.

### When to use

Use it only in the context of a Swagger UI session against the status service; ordinary integrations never call it. The endpoint index lists it as endpoint 22. It is not part of any transaction workflow and does not appear in the sandbox exit checklists.

### Preconditions

- A GET request to the status service host; the OpenAPI documents in this corpus were captured from https://hcxsbx.abdm.gov.in/<service>/api-docs, and the status service declares the server prefix /statushcxservice. - No JWE envelope, no x-hcx-* protocol headers and no correlation id; the docs do not state that a Bearer token is required for these discovery endpoints. - No request body.

### Postconditions

The service returns HTTP 200 with a small JSON object of UI settings. Nothing changes on NHCX and no callback follows. The documentation does not enumerate the settings, so the example below is illustrative; read the live response if you need specific values.

### Common mistakes

- Pointing at the gateway base https://apisbx.abdm.gov.in/pmjay/sbxhcx and expecting the per-service spec host; the docs advise swapping between the two URL shapes when a path 404s. - Treating the served document as the integration contract for gateway traffic; the handbook's gateway base and header conventions take precedence where the two disagree. - Sending a POST or a JSON body to a GET discovery endpoint. - Wrapping the call in JWE or adding x-hcx-* headers, which only apply to protocol APIs such as /v1/status.

### Best practices

- Use these endpoints for exploration and client generation in the sandbox, and cache the document rather than fetching it on every run. - Diff the served document against the corpus (Status service: OpenAPI 3.0.1, version 1.0.0) when behaviour changes unexpectedly. - Never let production traffic depend on the availability of the documentation endpoints. - Keep the /v1/status protocol rules in mind when reading the spec: x-hcx-correlation_id must carry the original request's correlation id.

### Related scenario

While preparing sandbox exit evidence, a payer's engineer captures screenshots of the status service's Swagger UI. The browser loads /swagger-resources/configuration/ui to decide how to render the page, then the resources list and the OpenAPI document. The engineer uses the rendered /v1/status operation to explain to the certification reviewer how the payer responds on the status callback when a provider asks about a dispatched preauthorisation.

### Specification

Chapter [Environments and addresses](/docs/nhcx/v1/reference/environments-and-addresses) 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.

Responses

200

The service returns HTTP 200 with a small JSON object of UI settings.