From a8ab2ab4390b8a1b571ea4d1a9ef23edb3f8fea0 Mon Sep 17 00:00:00 2001 From: iichr Date: Tue, 4 Aug 2026 17:27:29 +0100 Subject: [PATCH 1/2] feat: update spec to add app-level3 auth and new integration env --- schemas/changelog.md | 17 ++++++++++++ schemas/home-test-supplier-api.yaml | 43 +++++++++++++++++++++-------- 2 files changed, 49 insertions(+), 11 deletions(-) diff --git a/schemas/changelog.md b/schemas/changelog.md index 705b50e..d0d694e 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -26,10 +26,27 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche - [Version 1.1.6 - June 22, 2026 - Add order cancellation\*\*](#version-116---june-22-2026---add-order-cancellation) - [Version 1.1.7 - July 7, 2026 - Aligned API spec for APIM publication](#version-117---july-7-2026---aligned-api-spec-for-apim-publication) - [Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas for category and businessStatus](#version-118---july-22-2026---typed-codeableconcept-schemas) + - [Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access](#version-119---august-4-2026---document-apim-application-restricted-access) - [Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support](#version-200---july-20-2026---acute-consumer-order-support) --- +## Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access + +Changes to `home-test-supplier-api.yaml`: + +1. Replaced the generic bearer authentication scheme with APIM's `app-level3` + application-restricted signed-JWT security scheme. +2. Documented that suppliers authenticate their application, not an end user, + and linked to the NHS signed-JWT integration guide. +3. Added the sandbox, integration and production environment table. Only the + sandbox URL is currently available; integration and production remain + unavailable. +4. Corrected the sandbox documentation to state that it returns canned + responses and enabled "Try this API". + +--- + ## Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support Changes to supplier-api-spec-v2.yaml (new file, v1 remains unchanged): diff --git a/schemas/home-test-supplier-api.yaml b/schemas/home-test-supplier-api.yaml index e490331..511d88d 100644 --- a/schemas/home-test-supplier-api.yaml +++ b/schemas/home-test-supplier-api.yaml @@ -59,9 +59,14 @@ info: ## Security and authorisation - This draft uses bearer token authorisation because suppliers are system-to-system API consumers. + This API is application-restricted: we authenticate the calling supplier + application, but not an end user. - The final access level must be confirmed with the NHS API Platform team before production use. + Suppliers use this API unattended, with no end user present, to submit test + results and test-order status updates to HomeTest. + + To use this access mode, follow + [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication). ## Errors @@ -79,21 +84,39 @@ info: ## Environments and testing - A sandbox has been deployed to the NHS API Platform and is available under the `https://sandbox.api.service.nhs.uk/hometest-api` base URL. + | Environment | Base URL | + | --- | --- | + | Sandbox | `https://sandbox.api.service.nhs.uk/hometest-api` | + | Integration | Not yet available | + | Production | Not yet available | + + ### Sandbox environment + + Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): + + * is for early developer testing + * is open access, so does not allow suppliers to test authorisation + * returns canned example responses rather than processing live data. + + "Try this API" is enabled for this sandbox specification. + + ### Integration and production environments - The "Try this API" feature is disabled for this documentation-only publication until a sandbox endpoint is available. + Integration and production environments are not yet available. Integration + will support formal supplier testing with authorisation; production will + process live service requests. ## Onboarding Contact the HomeTest team to agree onboarding, supplier responsibilities and access to test environments. - version: 1.1.8 + version: 1.1.9 contact: name: NHS England - Digital Prevention Services Portfolio - Home Test Team email: england.hometest@nhs.net x-spec-publication: try-this-api: - disabled: true + disabled: false servers: - url: https://sandbox.api.service.nhs.uk/hometest-api @@ -1215,13 +1238,11 @@ components: diagnostics: "The requested order could not be found" securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT + app-level3: + $ref: https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3 security: - - bearerAuth: [] + - app-level3: [] tags: - name: Order Management From 5339decddaf4a257024cbd0ff8f78c9dd930c703 Mon Sep 17 00:00:00 2001 From: iichr Date: Fri, 7 Aug 2026 11:02:09 +0100 Subject: [PATCH 2/2] feat: bump spec up to 2.0.1 --- schemas/changelog.md | 4 ++-- schemas/home-test-supplier-api.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/changelog.md b/schemas/changelog.md index d0d694e..b6977fe 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -26,12 +26,12 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche - [Version 1.1.6 - June 22, 2026 - Add order cancellation\*\*](#version-116---june-22-2026---add-order-cancellation) - [Version 1.1.7 - July 7, 2026 - Aligned API spec for APIM publication](#version-117---july-7-2026---aligned-api-spec-for-apim-publication) - [Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas for category and businessStatus](#version-118---july-22-2026---typed-codeableconcept-schemas) - - [Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access](#version-119---august-4-2026---document-apim-application-restricted-access) - [Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support](#version-200---july-20-2026---acute-consumer-order-support) + - [Version 2.0.1 - August 4, 2026 - Document APIM application-restricted access](#version-201---august-4-2026---document-apim-application-restricted-access) --- -## Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access +## Version 2.0.1 - August 4, 2026 - Document APIM application-restricted access Changes to `home-test-supplier-api.yaml`: diff --git a/schemas/home-test-supplier-api.yaml b/schemas/home-test-supplier-api.yaml index 511d88d..bac29a6 100644 --- a/schemas/home-test-supplier-api.yaml +++ b/schemas/home-test-supplier-api.yaml @@ -109,7 +109,7 @@ info: ## Onboarding Contact the HomeTest team to agree onboarding, supplier responsibilities and access to test environments. - version: 1.1.9 + version: 2.0.1 contact: name: NHS England - Digital Prevention Services Portfolio - Home Test Team email: england.hometest@nhs.net