Signed JWT authentication - C# tutorial

Overview

This tutorial shows you how to connect to an application-restricted REST API using signed JWT authentication and the C# programming language.

To call an application-restricted API, you need to tell the API which application is calling it.

When using signed JWT authentication you need to authenticate your application by sending a JSON Web Token (JWT) to an authentication server, signed using your application's private key.

In exchange, you receive an access token which you need to include in the API request.

Setting up your environment

This example project was developed using .NET version 6.0, so you need to have this installed.

Check out the GitHub repository

You can find the code for this C# application-restricted REST API - signed JWT authentication tutorial in our GitHub repository

This project contains:

a JwtHandler class - this handles the generation and signing of the JWT
a AuthClientCredentials class - this handles the exchange of JWT with an access token from the auth server
a HelloWorld class located in the program.cs file - this requests an access token and then uses that access token to send a GET request to the specified endpoint

To follow this tutorial, download or clone this repository.

Create an application and generate a key pair

You need to create an application using our Developer portal.

This gives you access to your application ID and API key which you need to generate a JWT.

You also need to create a public and private key pair.

You register your public key with our authentication server and sign your JWT using your private key.

Create an application

To do this, follow Step 1 'Create an application' of our guide.

Notes:

when creating a new app, you need to select the 'Environment'. For this tutorial select 'Sandbox'.
when editing your application details and selecting the API you want to use, select 'Hello World (Sandbox)'. You might be prompted for a callback URL which is not required for the signed JWT authentication method, so you can enter a dummy value such as https://www.example.com.
make a note of your API Key

Generate a key pair

To do this, follow Step 2 'Generate a key pair' of our guide.

Make a note of the Key Identifier (KID) you have chosen.

Register your public key

To do this, follow Step 3 'Register your public key with us' of our guide.

Populate the project's environment variables

You should now have:

your application's API Key
a KID that you have chosen
your private key

To run the example tutorial, you need to set the following environment variables.

Variable name	Description
TOKEN_URL	The endpoint where you send your signed JWT in order to exchange for an access token. For the sandbox environment, the value is https://sandbox.api.service.nhs.uk/oauth2/token
CLIENT_ID	Your application's API Key
KID	The KID you chose when generating a public/private key pair
KEY_FILE	The filepath pointing to where you saved your private key
ENDPOINT	The URL for the API you wish to call. In this tutorial, we make a request to the Hello World Sandbox's application-restricted endpoint: https://sandbox.api.service.nhs.uk/hello-world/hello/application

You can set your environment variables in a file named .env. This project contains a sample env file to use:

rename env.sample to .env and modify it.
source it by running source .env

Run the code

Once you set the environment variables, you are ready to run the project.

Run the application

You should first source your environment variable file before executing your application.

Assuming you are using dotnet cli tool:

source .env

dotnet run

Run using Makefile

Alternatively you can set your environment variables in a file named .env. Then use the make command: make run. See the README for more info.

When you run the code, you should receive the following response from the Hello World application, showing you succeeded:

Create a developer account

To get started with our tutorials and APIs, you need to create a developer account.