Java SDK (`dev.orderly:orderly-java`)

Server-side Java SDK for creating embed sessions. Java 17+ required. No external dependencies — uses java.net.http.HttpClient.

Installation

Maven


<dependency>
    <groupId>dev.orderly</groupId>
    <artifactId>orderly-java</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle


implementation 'dev.orderly:orderly-java:0.1.0'

Quick Start


import dev.orderly.Orderly;
import dev.orderly.CreateSessionParams;
import dev.orderly.EmbedSession;
 
Orderly orderly = new Orderly("oh_your_secret_key");
 
EmbedSession session = orderly.createEmbedSession(
    new CreateSessionParams.Builder("user-123")
        .name("Acme Corp")
        .build()
);
 
String clientSecret = session.clientSecret(); // est_...

Spring Boot Example


import dev.orderly.Orderly;
import dev.orderly.CreateSessionParams;
import dev.orderly.EmbedSession;
import dev.orderly.OrderlyException;
import org.springframework.web.bind.annotation.*;
import java.util.Map;
 
@RestController
public class OrderlyController {
 
    private final Orderly orderly = new Orderly(System.getenv("ORDERLY_API_KEY"));
 
    @PostMapping("/api/orderly/session")
    public Map<String, String> createSession(@AuthenticationPrincipal User user)
            throws OrderlyException {
        EmbedSession session = orderly.createEmbedSession(
            new CreateSessionParams.Builder(user.getId())
                .name(user.getCompanyName())
                .email(user.getEmail())
                .build()
        );
 
        return Map.of("clientSecret", session.clientSecret());
    }
}

API Reference

`new Orderly(apiKey)`

Parameter	Type	Description
`apiKey`	`String`	Your Orderly secret key (`oh_...`)

`new Orderly(apiKey, baseUrl)`

Parameter	Type	Description
`apiKey`	`String`	Your Orderly secret key (`oh_...`)
`baseUrl`	`String`	API base URL (default: `https://api.orderly.dev`)

`orderly.createEmbedSession(params)`

Creates a session token. Throws OrderlyException on API errors.

CreateSessionParams.Builder methods:

Method	Type	Required	Description
`Builder(externalId)`	`String`	Yes	Unique user ID in your system
`.name(name)`	`String`	No	Display name
`.email(email)`	`String`	No	Email address
`.allowedBridgeTypes(types)`	`List<String>`	No	Restrict bridge types
`.enabledFeatures(features)`	`List<String>`	No	Feature modules
`.scopes(scopes)`	`List<String>`	No	Permission scopes
`.ttl(ttl)`	`int`	No	Session TTL in seconds

EmbedSession record:

Field	Type	Description
`clientSecret()`	`String`	`est_` token for the frontend
`sessionId()`	`String`	Session ID
`expiresAt()`	`String`	ISO 8601 expiration
`scopes()`	`List<String>`	Granted scopes
`enabledFeatures()`	`List<String>`	Enabled features

Error Handling


import dev.orderly.OrderlyException;
 
try {
    EmbedSession session = orderly.createEmbedSession(
        new CreateSessionParams.Builder("user-123").build()
    );
} catch (OrderlyException e) {
    System.err.println("API error: " + e.getMessage());
    System.err.println("Status code: " + e.getStatusCode());
}

Java SDK (dev.orderly:orderly-java)