Auth0 Java SDK

When adding or modifying tests, distinguish between generated and hand-maintained code:

Generated Tests

Most Management API tests are Fern-generated and reside under the mgmt tree. Do not hand-edit these files; any changes to their behavior must be made in the specification/generator.

Hand-maintained Tests

Hand-maintained tests (which are listed in .fernignore to prevent clobbering) include:

• Files in src/test/java/com/auth0/client/auth/ (Authentication API)
• Specific management files like ManagementApiBuilderTest.java, DynamicTokenManagementTest.java, OAuthTokenSupplierTest.java, CustomDomainInterceptorTest.java, and CustomDomainHeaderIntegrationTest.java.

Shared Infrastructure

Reuse existing shared test infrastructure instead of creating new HTTP-assertion helpers. Key utilities are located under com/auth0/client/:

• MockServer
• RecordedRequestMatcher
• UrlMatcher
• AssertsUtil

In v5, response fields that are nullable in the Auth0 API use OptionalNullable<T>. This type provides a way to distinguish between a field being absent and a field being explicitly null.

Available Methods

• isPresent(): Returns true if a value is present.
• isAbsent(): Returns true if the field was omitted.
• isNull(): Returns true if the API explicitly returned null.
• wasSpecified(): Returns true if the field was present in the response (either as a value or as null).
• get(): Returns the value. Throws IllegalStateException if the field is absent or null.
• getValueOrNull(): Returns the value or null.
• orElse(fallback): Returns fallback if the field was absent, but returns null if the field was explicitly null.
• map(function): Maps the value if present.
• toOptional(): Converts the OptionalNullable to a standard java.util.Optional. This treats both 'absent' and 'explicit-null' states as an empty Optional.

Affected Getters

• Session/UpdateSession/GetSessionResponseContent: getCreatedAt(), getUpdatedAt(), getAuthenticatedAt(), getIdleExpiresAt(), getExpiresAt(), getLastInteractedAt()
• Refresh Token (Get/Update/ResponseContent): getCreatedAt(), getIdleExpiresAt(), getExpiresAt(), getLastExchangedAt()
• SessionAuthenticationSignal: getTimestamp()
• FlowActionFlowMapValueParams: getFallback()

// v4 approach (will fail in v5)
Optional<SessionDate> created = session.getCreatedAt();
session.getCreatedAt().ifPresent(this::audit);

// v5 approach: simplest migration using .toOptional()
Optional<SessionDate> created = session.getCreatedAt().toOptional();
session.getCreatedAt().toOptional().ifPresent(this::audit);

// v5 approach: distinguishing between absent and explicit null
OptionalNullable<SessionDate> expires = session.getExpiresAt();
if (expires.isPresent()) {
    handle(expires.get());
} else if (expires.isNull()) {
    // the API explicitly returned null for this field
} else {
    // the API omitted the field
}

The SDK provides two ways to perform asynchronous operations depending on which API you are using.

Management API

The Management API provides a dedicated AsyncManagementApi client. All operations on this client return a CompletableFuture.

Authentication API

The AuthAPI supports asynchronous execution via the .executeAsync() method on request objects, which returns a CompletableFuture.

// Management API Async
AsyncManagementApi asyncClient = new AsyncManagementApi(clientOptions);
CompletableFuture<GetUserResponseContent> future = asyncClient.users().get("user_id");
future.thenAccept(user -> {
    System.out.println(user.getEmail());
});

// Authentication API Async
AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}").build();
CompletableFuture<TokenHolder> future = auth.requestToken("https://{YOUR_DOMAIN}/api/v2/").executeAsync();
future.thenAccept(holder -> {
    String accessToken = holder.getBody().getAccessToken();
});

When creating or updating a branding theme, you can customize several visual aspects using the following configuration objects:

• BrandingThemeBorders: Controls the radius and weight of borders for buttons, inputs, and widgets. Supports styles like BrandingThemeBordersButtonsStyleEnum.PILL.
• BrandingThemeColors: Defines the color palette for various UI elements including bodyText, error, header, primaryButton, widgetBackground, and inputBackground.
• BrandingThemeFonts: Manages typography. You can set a global fontUrl and specify individual styles (bold, size) for bodyText, buttonsText, inputLabels, links, subtitle, and title.
• BrandingThemePageBackground: Configures the page's appearance using backgroundColor, backgroundImageUrl, and pageLayout (e.g., BrandingThemePageBackgroundPageLayoutEnum.CENTER).
• BrandingThemeWidget: Customizes the Auth0 widget, including logoUrl, logoHeight, logoPosition, headerTextAlignment, and socialButtonsLayout.