Java Quickstart

Plain Java EE / Jakarta servlets with a Servlet filter that verifies X-Auth bearers. Use the same SDK from any JVM framework.

Artifact: com.xentranet:x-auth-java JDK 17+ · Jakarta Servlet 5+ Time: ~7 min

Add the dependency

Pull the SDK from Maven Central.

pom.xml

<dependency>
  <groupId>com.xentranet</groupId>
  <artifactId>x-auth-java</artifactId>
  <version>1.0.0</version>
</dependency>

Construct a singleton

Build the SDK once at app start with your tenant id. The client is thread-safe.

XAuthHolder.java

package com.example.xauth;

import com.xentranet.xauth.XAuth;

public final class XAuthHolder {
    public static final XAuth INSTANCE = XAuth.builder()
        .tenantId(System.getenv("XAUTH_TENANT_ID"))
        .build();
}

Add a verifying filter

The filter validates the bearer, asserts the action, and attaches the bound transaction context to the request.

VerifyFilter.java

package com.example.xauth;

import com.xentranet.xauth.Expect;
import com.xentranet.xauth.TransactionContext;
import jakarta.servlet.*;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@WebFilter(urlPatterns = "/api/transfer")
public class VerifyFilter implements Filter {
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws ServletException {
        HttpServletRequest http = (HttpServletRequest) req;
        String bearer = http.getHeader("Authorization").replace("Bearer ", "");
        try {
            TransactionContext ctx = XAuthHolder.INSTANCE.verify(bearer,
                Expect.action("transfer"));
            req.setAttribute("transaction_ctx", ctx);
            chain.doFilter(req, res);
        } catch (Exception e) {
            ((HttpServletResponse) res).sendError(401, "invalid_transaction");
        }
    }
}

Use the bound context in your servlet

Pull the verified TransactionContext off the request and proceed.

TransferServlet.java

@WebServlet("/api/transfer")
public class TransferServlet extends HttpServlet {
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse res) {
        TransactionContext ctx = (TransactionContext) req.getAttribute("transaction_ctx");
        ledger.transfer(ctx);
        res.getWriter().write("{\"ok\":true}");
    }
}

Using Spring Boot? See the dedicated Spring Boot quickstart with @Verified annotations.

Java Quickstart

Add the dependency

Construct a singleton

Add a verifying filter

Use the bound context in your servlet

Next steps