Skip to main content
Creating a new NHS England: NHS England and NHS Digital merged on 1 February 2023. More about the merger.

Signing Service API

Generate an electronic signature using your smartcard.

This specification is written from an OAS file.


Use this API to digitally sign one or more prescriptions from an application that cannot communicate directly with an NHS smartcard reader.

You cannot currently use this API to:

  • produce signatures using an algorithm other than RS1 (RSASSA-PKCS1-v1_5 with SHA-1)

End users of this API must be authenticated with an NHS smartcard or modern alternative.

Using this API

Use this API exclusively for browser-based applications.

To use this API, you must:

  1. Create an RSA key pair with a key length of 4096 bits or greater
  2. Contact us, and provide the following:
  • your public key, which we store in our JSON Web Key Set (JWKS) and give you a Key ID
  • a callback URL which our service can use to notify your system when the signing process is complete

To generate signatures:

  1. Run Credential Management, on the same machine as the web browser used to access the Signing Service Client. In production environment, Credential Management supports Windows only. In non-production environments, a mock implementation is available for all operating systems. This creates a fake signature which must not be used in production.
  2. For each prescription to be signed, make a request to the POST /$prepare endpoint of the Electronic Prescription Service - FHIR API and save the response.
  3. Create a JSON Web Token (JWT) containing the Key ID and the data to be signed (see signature-request for more info)
  4. Sign the JWT with the RS512 algorithm using your private key.
  5. Send the JWT to the Signing Service using the POST /signaturerequest endpoint. The service responds with a token representing your signature request and a redirect URL.
  6. Redirect the user’s browser to this URL in order to access the Signing Service Client. The Signing Service Client communicates with Credential Management to generate one or more signatures using an NHS smartcard. Append &mock=true to the redirect URL to access a mock implementation of the Credential Management integration. The Signing Service calls your registered callback URL when the signing process is complete, including the token for the payload.
  7. Send the token received by the callback URL to the GET /signatureresponse endpoint to obtain the signatures.

Who can use this API

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must do this before you can go live (see ‘Onboarding’ below).

The following APIs are related to this one:

API status and roadmap

This API is in alpha, meaning:

  • the API is available in our sandbox and integration test environments
  • the API is not yet available for production use
  • we might make breaking changes, but only if we cannot avoid it, and we'll give advance notice

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.

If you have any other queries, please contact us.


This API is RESTful.

End-users of the API require Credential Management to be installed and running on their local machine.

Network access

This API is available on the internet, although access using NHS smartcards (see below) currently requires a connection to the Health and Social Care Network (HSCN).

Interactions are heavily influenced by the OAuth flow for user authentication:

  • Application flow is controlled predominantly by HTTP redirects issued to the browser
  • The client receives a token representing their signature request. The token can then be exchanged for the actual signature data

Security and authorisation

This API is user-restricted, meaning an end user must be present and authenticated to use it.

The end user must be:

  • a healthcare professional
  • strongly authenticated using an NHS smartcard

The API uses Open ID Connect to authenticate the end user and OAuth 2.0 to authorise the calling system. It supports the following security patterns using NHS Care Identity Service 2 (NHS CIS2) authentication and authorisation:

Environments and testing

Purpose URL
Integration test (smartcard authentication)
Production Not yet available

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is stateless, so it does not store data
  • is open access, so does not allow you to test authorisation

For more details on sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.

Integration testing

Our integration test environment:

  • is for formal integration testing
  • is stateful, so it does persist data
  • includes authorisation, with smartcard and non-smartcard options

For more details see integration testing with our RESTful APIs.


We are hoping to make the assurance process as lightweight and as self-service as possible.

Endpoints: SignatureRequest

Request signature generation

post /signaturerequest


Request signatures, from a minimum of 1 up to a maximum of 250, and receive a token in exchange.



Content type: text/plain


Valid JWT


Name Description

A signed JWT containing the data to be signed by the service.

The JWT header must include the following fields:

  • typ - the type of the token. This must be JWT.
  • alg - the algorithm used to sign the token. This must be RS512.
  • kid - the ID of the key which the service uses to verify the JWT signature.

The JWT payload must include the following fields:

  • iss - the issuer of the token. This must be the client ID of your Apigee app.
  • sub - the subject of the token. This must be the SDS user ID of the person requesting the signature.
  • aud - the intended audience of the token. This must be the URL of the Signing Service.
  • exp - the expiry time of the token. This must be at most 10 minutes in the future.
  • iat - the time the token was issued.
  • algorithm - the algorithm which is used to sign the prescription itself (not the JWT). Values are defined in JSON Web Signature and Encryption Algorithms. At present, only RS1 is supported.
  • payloads - a list of objects, each containing the following fields:
    • id - an identifier for the payload. This can be used to match up the signature with the payload which was signed.
    • payload - the base64 encoded payload to be signed.

The JWT signature must be present, and must use the RS512 algorithm.

Pattern: ^[a-zA-Z0-9\-_]+?\.[a-zA-Z0-9\-_]+?\.[a-zA-Z0-9\-_]+?$


HTTP status: 200

Successful upload


Content type: application/json



Name Description

The response returned by the service when a redirect is required to continue the signing process.

string uuid

A token representing the signature creation request. This can be used to retrieve the signature once it has been created.

Example: f523a772-24f2-45d6-a8da-59b48de0231a
string uri

The URL which you should redirect to in order to continue the signing process. When redirecting to the Signing Service Client, you may append &mock=true to the query string to request a mock implementation of the Credential Management integration.

HTTP status: 4XX

Unsuccessful operation


Content type: application/json


Endpoints: SignatureResponse

Retrieve signatures

get /signatureresponse/{token}


Retrieve signatures for a given payload token.


Path parameters
Name Description

UUID (uuid)

The payload token returned in response to the signature creation request



HTTP status: 200

Successful retrieval


Content type: application/json



Name Description

The response to a signature retrieval request.


The signatures which were generated and the ids which link them to their payloads.


A signature and the id which links it to its payload.


The id of the payload which was signed to produce this signature.

Example: e77bf3e8-bcf5-4431-91a2-22672b27662a
string base64

A signature, encoded in base64.

Example: XpjsKXPfUW708rGPuOAphlr4/UA23f3bhdBOocEJ17BXV0Jruz1E1KLFQwq37EJfnVo/WCLTSjgkkp0BWj5bG3JjEfj78ZjI1yVSRbfbVXXQX0GLZmiSGJrhWnFZt8cFrxO1MFAtSLmKfyXKzbuHsLTmsHQKpXCRdZnFmKBojLmp7NBr0lLE8Phttu8F2Eaeu2wPQ84p1iNW91fo1H+SFVxC+BRoPI1polXg42ceTjoJ7+FqYPDHfC7nNFIgTYJZlQdboMNbndv6BPDuFq0wusQjDQ4zMZ+8ClpRdt3iKmylXNmKkJA15W0pFbGq0Xnf3S1MXWElkaCIUCdGK2WsPA==
string base64

The certificate associated with the private key used to generate the signature, represented in X.509 version 3 format and encoded in base64.

HTTP status: 4XX

Unsuccessful operation


Content type: application/json


Last edited: 18 October 2022 10:40 am