If your SaaS product’s backend is built with Java—or a JVM-compatible language such as Kotlin, Groovy, Scala, or Clojure—and you want to incorporate WorkOS’ Admin Portal functionality, you can do a dry-run of the Admin Portal integration using our example Java app. It makes use of the WorkOS Kotlin SDK.
If you get stuck while following the steps below and aren't able to resolve the issue by reading our API reference or Admin Portal Setup Guide, please reach out to us at support@workos.com so we can help!
A free WorkOS account, and each of these installed on your machine:
- Java version 1.8+
- The Java Development Kit (JDK), which includes the Java Runtime Environment (JRE)
- In your CLI, navigate to the directory into which you want to clone the Java example app git repo:
$ cd ~/Desktop- Clone the main Java example app repo:
# HTTPS
$ git clone https://github.com/workos/java-example-applications.git
or
# SSH
$ git clone git@github.com:workos/java-example-applications.git- Navigate to the cloned repo:
$ cd java-example-applications/- Obtain and make note of your WorkOS API key and WorkOS Client ID from the WorkOS Dashboard. The locations of these values are shown in the screenshots below.
- Create a .env file in the java-example-applications/ directory to store the environment variables:
$ touch .env- Open the new .env file with your preferred text editor and replace the placeholder values for WORKOS_API_KEY and WORKOS_CLIENT_ID:
WORKOS_API_KEY=your_api_key_here
WORKOS_CLIENT_ID=your_project_id_hereThe .env file is listed in this repo's .gitignore file, so your sensitive information will not be checked into version control. This is an important consideration for keeping sensitive information such as API keys private. The WorkOS Kotlin SDK will read your API key and Client ID from the .env file.
- Start the server by running this command in the CLI while you’re in the java-example-applications/ directory:
$ ./gradlew :java-directory-sync-example:run- Navigate to http://localhost:7001. Select an Organization to view its directories. If you don’t see any Directories, it’s time to add your first one!
Nice work! You just set up Directory Sync for your Java app!
If you get stuck while following the steps below and aren't able to resolve the issue by reading our API reference or Directory Sync Setup Guide, please reach out to us at support@workos.com so we can help!

