Java Quickstart

This guide will help you integrate Descope's Java SDK into your backend application. Follow the steps below to get started.

Use this pre-built prompt to get started faster.

Install Backend SDK

Install the SDK by including the SDK in your pom.xml file (for installation via Maven).

pom.xml

<dependency>
	<artifactId>java-sdk</artifactId>
	<groupId>com.descope</groupId>
	<version>[1.0.0,)</version>
</dependency>

Import and Setup Backend SDK

You'll need import and setup all of the packages from the SDK.

If you're using a custom domain with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="__BaseURL__") when initializing descope_client.

Application.java

package com.descope.java_sample_app;

// descope imports start
import com.descope.client.*;
import com.descope.exception.DescopeException;
import com.descope.model.jwt.Token;
import com.descope.sdk.auth.AuthenticationService;
// descope imports end
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class JavaSampleAppApplication {

	DescopeClient descopeClient = new DescopeClient(
		Config.builder().projectId("__ProjectID__").build()
	);
	AuthenticationService authService = descopeClient.getAuthenticationServices().getAuthService();

	public static void main(String[] args) {
		SpringApplication.run(JavaSampleAppApplication.class, args);
	}

}

Implement Session Validation

You will need to then fetch the session token from the Authorization header of each request, and use the SDK to validate the token.

The frontend SDK will store the session token in either a cookie or your browser's local storage. If using a cookie, the token will be sent to your app server automatically with every request.

Note

By default, the aud claim in your session token is your Descope Project ID. Always check that value (or your custom audience) after validating, so you only accept tokens issued for your application.

You can change the audience in a JWT Template if you need a custom value.

Application.java

@SpringBootApplication
@RestController
public class JavaSampleAppApplication {

	public static void main(String[] args) {
		SpringApplication.run(JavaSampleAppApplication.class, args);
	}
	
	public void validateSession(String sessionToken, String refreshToken) {
		var descopeClient = new DescopeClient(Config.builder().projectId("__ProjectID__").build());

		AuthenticationService as = descopeClient.getAuthenticationServices().getAuthService();
		try {
			Token t = as.validateSessionWithToken(sessionToken);
			if (!"__ProjectID__".equals(t.getProjectId())) {
				// Reject: token issued for a different project
				throw new DescopeException("aud claim mismatch");
			}
		} catch (DescopeException de) {
			// Handle the unauthorized error
		}

		// If validation fails because the session expired, refresh it
		try {
			Token t = as.refreshSessionWithToken(refreshToken);
		} catch (DescopeException de) {
			// Handle the unauthorized error
		}

		// If JWT rotation is enabled in your project settings, refreshing a session also returns a new
		// refresh token. Use the AuthenticationInfo variant to retrieve it
		try {
			AuthenticationInfo authInfo = as.refreshSessionWithTokenAuthenticationInfo(refreshToken);
			String newRefreshJwt = authInfo.getRefreshToken().getJwt();
		} catch (DescopeException de) {
			// Handle the unauthorized error
		}

		// Or validate and refresh in one call
		try {
			Token t = as.validateAndRefreshSessionWithTokens(sessionToken, refreshToken);
		} catch (DescopeException de) {
			// unauthorized error
		}

		try {
			AuthenticationInfo authInfo = as.validateAndRefreshSessionWithTokensAuthenticationInfo(sessionToken, refreshToken);
			String newRefreshJwt = authInfo.getRefreshToken().getJwt();
		} catch (DescopeException de) {
			// unauthorized error
		}
	}
	
}

Next Steps

Once you've implemented the basic session validation, you can enhance your application with these additional features:

User Management

Learn how to create, update, and manage users in your application.

Role-Based Access Control

Implement fine-grained access control using roles and permissions.

API Gateway Session Validation

Secure your API endpoints with session validation middleware.

Set up M2M Authentication

Implement M2M authentication with Descope.

Additional Resources

Have You Implemented the Frontend Yet?

When integrating Descope into your application, you have three options depending on how much control you want over your frontend authentication experience and session management:

Option	Description	Best For
Use Descope Flows	Design your authentication screens and flows visually in the Descope Console with little or no frontend code. We handle all session management for you.	Fastest setup with minimal custom frontend work.
Use Descope Client SDKs	Build your own login screens and authentication experiences in your frontend using code, while relying on Descope's SDKs to manage sessions (login, logout, refresh).	Customizable UX with simplified session handling.
Use Descope Backend SDKs	Build your own frontend and your own backend APIs for authentication. You fully manage sessions, tokens, and authentication logic yourself.	Maximum flexibility and control, at the cost of more engineering effort.

Descope Flows

Design login screens and authentication flows visually without writing code, and embed them into your app.

Descope Client SDKs

Build custom login screens in your frontend using code, while we manage session tokens and refreshing for you.

Was this helpful?