Java project

GitHub license test docs Maven 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");