Skip to main content

Other

Swagger security configuration

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

GET/swagger-resources/configuration/security

### Business purpose

Swagger UI reads this endpoint to learn how to present authorisation inputs (such as a bearer token field) when a user tries operations from the browser. It describes UI behaviour only; it does not issue tokens, and it is unrelated to the client-credentials flow at /get/session or to the JWE encryption that protects protocol payloads. The endpoint index describes it as the Swagger security configuration.

### When to use

Use it only in a Swagger UI session against the status service; integrations never need it. The endpoint index lists it as endpoint 23. It is not part of any transaction workflow, not a source of credentials, and not referenced by 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 describing how Swagger UI should handle security inputs. Nothing changes on NHCX, no token is issued and no callback follows. The documentation does not enumerate the fields, so the example below is illustrative.

### 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. - Mistaking this endpoint for an authentication API; tokens come only from the client-credentials call documented in the authentication chapter.

### 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

A provider's engineer wants to try /v1/status from Swagger UI in the sandbox. The UI fetches /swagger-resources/configuration/security to decide how to show the authorisation dialog, and the engineer pastes a Bearer token obtained separately from the client-credentials call. Because the status request body must be a JWE built with the payer's certificate, the engineer ultimately uses the UI only to confirm the schema and runs the real status request from the integration code, which reuses the original preauth correlation id.

### 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 describing how Swagger UI should handle security inputs.