# 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:

```xml
<dependency>
    <groupId>io.suger.sdk</groupId>
    <artifactId>suger-java-client</artifactId>
    <version>3.129.0</version>
</dependency>
```

For the latest released version, see [suger-java-client on Maven Central](https://central.sonatype.com/artifact/io.suger.sdk/suger-java-client).

## Step 2: Get an OAuth access token

The Suger API uses the OAuth 2.0 client-credentials flow. First, create an
[OAuth App](https://doc.suger.io/get-started/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:

```java

// 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](https://doc.suger.io/get-started/oauth-app/)
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>`:

```java
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:

```java
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)

:::warning
API-key authentication is **deprecated**. New integrations should use the OAuth
access token shown above. The API-key example below is retained only for
existing integrations.
:::

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

```java
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.