Java project

GitHub licenseGitHub license testtest docsdocs Maven CentralMaven Central

Terra Java Client Library

Terra provides an API wrapper library for Java to help integrate with your application faster.

Features include:

  • Fully asynchronous HTTP request wrapping
  • Webhook parsing
  • Webhook event dispatching
  • User management

View Javadoc


terra-client is available for download from Maven Central.


  • Java 11 or later

Gradle users

Add this dependency to your project's build file:

implementation "co.tryterra:terra-client:<version>"

Maven users

Add this dependency to your project's pom:




In order to interact with the Terra API using this library, you need an instance of TerraClientV2. This is created using TerraClientFactory:

TerraClientV2 client = TerraClientFactory.getClientV2("API KEY", "DEV ID");

In order to parse and handle webhook requests from Terra, you instead need an instance of WebhookHandlerUtility:

WebhookHandlerUtility webhookUtility = new WebhookHandlerUtility("WEBHOOK SECRET");

Authentication & User Management

This library does not provide the facilities for directly authenticating a user - you can currently only interact with users that have been authenticated previously.

Creating a User object

API request methods of your TerraClientV2 instance accept both User and PartialUser objects - this allows you not to make a web request to fetch a full User object if you are certain that a user with the given ID exists.

When any API request is made, a new User object will be returned with the response. (See TerraApiResponse#getUser())

With API request

User user = client.getUser("USER ID");

Without API request

PartialUser user = client.userFromId("USER ID");


Future<TerraApiResponse<Void>> resp = client.deauthenticateUser(user);
if (resp.get().isSuccessful()) {
  System.out.println("User deauthenticated");