Skip to content

feat: Update hometest supplier spec to add app-level3 auth and new integration environment #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
iichr wants to merge 2 commits into
base: main
Choose a base branch
from
+49 −11
Open

feat: Update hometest supplier spec to add app-level3 auth and new integration environment #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8ab2ab
feat: update spec to add app-level3 auth and new integration env
iichr Aug 4, 2026
5339dec
feat: bump spec up to 2.0.1
iichr Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions schemas/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,23 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche
- [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 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 2.0.1 - 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".

---

Expand Down
43 changes: 32 additions & 11 deletions schemas/home-test-supplier-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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: 2.0.1
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
Expand Down Expand Up @@ -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
Expand Down