Java SDK

Follow these steps to get started with the Suger Java SDK.

Step 1: Add Maven Dependency

To include the Suger SDK in your project, add the following dependency to your pom.xml file:

<dependency>
    <groupId>io.suger.sdk</groupId>
    <artifactId>suger-java-client</artifactId>
    <version>3.14.0</version>
</dependency>

3.14.0 is the current release on Maven Central. Earlier releases use a v-prefixed coordinate (for example v3.132.0); if your pom.xml still references one of those, keep it pinned as-is rather than assuming a numeric ordering. For the full version list, see suger-java-client on Maven Central.

Step 2: Get an OAuth access token

The Suger API uses the OAuth 2.0 client-credentials flow. First, create an OAuth App in your organization settings to get a Client ID and Client Secret. Then exchange them for a short-lived (1 hour) bearer token:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

// Exchange OAuth App credentials for a bearer token. Cache the returned token
// and request a new one when it expires (default lifetime: 1 hour).
public String getAccessToken(String clientId, String clientSecret) throws Exception {
    String form = "grant_type=client_credentials"
        + "&client_id=" + clientId
        + "&client_secret=" + clientSecret
        + "&resource=https://api.suger.cloud";
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://apiv2.suger.cloud/oauth2/token"))
        .header("Content-Type", "application/x-www-form-urlencoded")
        .POST(HttpRequest.BodyPublishers.ofString(form))
        .build();
    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    // Read the "access_token" field from the JSON response with your JSON library.
    return parseAccessToken(response.body());
}

The resource=https://api.suger.cloud parameter is required — it scopes the issued JWT to the Suger API. See API Access for the full token exchange, caching, and rotation details.

Step 3: Create a Client

Create a client and attach the bearer token. APIKeyAuth writes the Authorization header verbatim, so pass the OAuth token as Bearer <token>:

public ApiClient client(String accessToken) {
    ApiClient apiClient = new ApiClient();
    apiClient.setBasePath("https://api.suger.cloud");
    ApiKeyAuth APIKeyAuth = (ApiKeyAuth) apiClient.getAuthentication("APIKeyAuth");
    APIKeyAuth.setApiKey("Bearer " + accessToken);
    return apiClient;
}

Step 4: Use the Client

Now that you have your client set up, you can call Suger services. Here’s a simple example of how to make a service call:

public WorkloadOffer getOffer(ApiClient client, String orgId, String offerId) throws ApiException {
    OfferApi offerApi = new OfferApi(client);
    return offerApi.getOffer(orgId, offerId);
}

Legacy authentication (API key)

To authenticate an existing integration with an API key, pass it as Key <key> instead of a bearer token:

ApiKeyAuth APIKeyAuth = (ApiKeyAuth) apiClient.getAuthentication("APIKeyAuth");
APIKeyAuth.setApiKey("Key " + yourApiKey);

Conclusion

You are now ready to use the Suger Java SDK in your application! For more detailed information and advanced usage, please refer to the official documentation.