API reference

Annotations

@Auth

May be used on a controller class, a method, or a composed annotation.

@Auth(
    roles = { "admin", "auditor" },
    permissions = { "report:read" },
    mode = AuthMode.ANY
)

@Anonymous

Marks a class or method that does not require authentication. A method-level declaration takes precedence, and no current-user identity is created for the endpoint.

AuthPrincipal<T>

An immutable representation of the current identity:

The constructor defensively copies collections and maps. id cannot be null.

CurrentAuth

A Spring-managed singleton facade backed by the request thread context:

currentAuth.isAuthenticated();
currentAuth.getUserId();
currentAuth.getUser(AppUser.class);
currentAuth.getRoles();
currentAuth.getPermissions();
currentAuth.hasRole("admin");
currentAuth.hasPermission("GET", "/api/users/42");

requirePrincipal() throws IllegalStateException if no identity is available. It is normally used only on code paths already protected by @Auth.

AuthInterceptor<T>

The required method is:

AuthPrincipal<T> authenticate(String token, HttpServletRequest request);

Optional methods to override are resolveToken, authorize, bind, clear, and resolveRequestPath. When the application provides this bean, the auto-configured PermitAllAuthInterceptor backs off.

ApiResponse<T>

Fields: success, code, message, data, and timestamp.

ApiResponse.success(data);
ApiResponse.success("created", data);
ApiResponse.failure("ORDER_CLOSED", "Order is already closed");
ApiResponse.failure("INVALID_LINES", "Some lines are invalid", details);

PageResult<T>

new PageResult<>(items, total, page, pageSize);

Fields: items, total, page, and pageSize. getTotalPages() rounds up when calculating the number of pages.

Exception matrix

Every exception extends SmartMvcException and does not generate a stack trace.

new BusinessException(message) uses the default code BUSINESS_ERROR. You can also provide an application-specific code, message, and details for a business rejection that the client can understand and handle.