Signed JWT authentication - Java tutorial

This tutorial shows you how to connect to an application-restricted REST API using signed JWT authentication and the Java 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.

We developed this example project using Java 17 and maven 3.8.6, so you need to have those installed.

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

This project contains:

• an Auth class - the methods of this class handle the generation and signing of the JWT, and exchanging the JWT for an access token with the authentication server
• a HelloWorld class - the methods of this class make an application-restricted request to the API endpoint
• the App class - this contains the main entry point to run the program. This program gets an access token using a signed JWT and uses the access token to call the API.

To follow this tutorial, download or clone this repository.

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.

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 

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

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

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

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.

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

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

Use the following commands to run the project using maven from the command line:

• mvn clean install - this compiles, tests and packages your code.
• java -jar target/hello-world-auth-example-1.0-SNAPSHOT-jar-with-dependencies.jar - this runs the executable jar file produced in the previous step.

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:

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