Blog

A Java API can become unsafe long before anyone attempts an advanced attack. A stack trace in a response, a client-controlled role field, an authorization header in a log, or an unbounded request body can expose data or make a service easier to disrupt. Treat every HTTP request as untrusted input and every response as an intentional disclosure.

Security is not a layer added shortly before deployment. Identity, permissions, validation, error handling, secrets, and operational controls should shape every endpoint. The examples use ideas common in Spring Boot, though the same principles apply to Jakarta REST, Javalin, Micronaut, and other Java frameworks.

Start with a small, explicit API surface

Every route should represent a defined business action, accept only the fields that action needs, and return only data the caller is allowed to see. Avoid exposing persistence entities directly. Database entities often include internal IDs, account status, password-reset metadata, audit flags, or relationships that do not belong in an API response.

Use separate request and response DTOs. A registration request may need an email address and password, while a public account response might include only a display name and generated account ID. Separate types reduce the risk of mass assignment, where a client submits fields such as role, isAdmin, or accountLocked that must remain under server control.

public record UpdateProfileRequest(
    @NotBlank @Size(max = 60) String displayName
) {}

public record ProfileResponse(
    UUID id,
    String displayName
) {}

Even if JSON deserialization ignores unknown properties, reject or monitor unexpected fields when practical. Silent acceptance hides client mistakes and can mask probing. Versioning also makes contract changes safer: use a clear path such as /api/v1/profiles or a documented media-type strategy instead of quietly changing what existing fields mean.

Authenticate users, then authorize every action

Authentication answers, “Who is making this request?” Authorization answers, “May this identity perform this action on this resource?” A valid login token does not prove that someone may read another user’s record or perform an administrative action.

Choose an identity model deliberately

For browser-based applications, secure session cookies may be appropriate. In most cases, cookies should use Secure, HttpOnly, and a SameSite setting that fits the application’s cross-site requirements. Because browsers send cookies automatically, state-changing requests also need CSRF protection.

Bearer tokens are common for mobile clients and service-to-service APIs. Before trusting their claims, verify the signature, issuer, audience, expiration time, and relevant key identifier. Keep access tokens short-lived. If you use refresh tokens, protect them as carefully as passwords, rotate them where possible, and revoke or invalidate them after compromise, logout, or major account changes.

Do not build token validation by splitting strings or decoding Base64 data alone. A token that can be decoded has not necessarily been verified. Use a maintained authentication library or framework integration configured to verify signatures against trusted keys.

Apply both role and ownership checks

Role-based access control works well for broad permissions. For example, only support staff may access a support workflow. It does not cover user-owned resources by itself. An endpoint such as GET /api/v1/orders/{id} must confirm that the authenticated principal owns the order unless an explicitly authorized staff role may access it.

Order order = orderRepository.findById(orderId)
    .orElseThrow(() -> new ResourceNotFoundException());

if (!order.getCustomerId().equals(currentUser.id())) {
    throw new AccessDeniedException("Not permitted");
}

Apply ownership checks to read, update, delete, download, and nested-resource routes. This prevents insecure direct object reference issues, where changing an ID in a URL reveals another user’s data. In most applications, authorization decisions belong close to the service method that performs the action rather than relying only on controller conventions.

Validate input at the boundary and enforce rules in the service layer

Validation serves two purposes: it confirms that input is safe to process structurally, and it enforces business constraints. Bean Validation annotations are a useful first layer for DTO fields. Use size limits, format checks, numeric ranges, and required-field checks. Add @Valid to request parameters so invalid payloads fail before reaching business logic.

public record CreateCommentRequest(
    @NotBlank @Size(max = 2_000) String text
) {}

@PostMapping("/posts/{postId}/comments")
public CommentResponse createComment(
        @PathVariable UUID postId,
        @Valid @RequestBody CreateCommentRequest request) {
    return commentService.create(postId, request);
}

Field validation is not complete security. A properly formatted email address does not grant permission to change an organization setting. A number inside an allowed range can still violate a business rule. Check server-side state, ownership, workflow transitions, and quotas in the service layer.

Set limits beyond the DTO. Configure a maximum HTTP request size, cap multipart uploads, limit pagination parameters, and use reasonable timeouts. A technically valid but oversized request can consume memory, database capacity, or worker threads. For uploads, accept only file types the application truly needs, generate filenames on the server, store files outside executable web roots, and scan or quarantine them according to the system’s risk level.

Use safe database access patterns

Parameterized queries through JPA, JDBC prepared statements, or a reputable query builder keep user values separate from query syntax. Do not construct JPQL, SQL, or native-query fragments by concatenating request values. Sorting and filtering deserve the same care: SQL parameters cannot safely replace arbitrary column names, so map a short allowlist of client-visible sort keys to known server-side fields.

For example, allow createdAt and status as sort options, then reject everything else. Never pass a client-provided value directly into an ORDER BY clause or other dynamic query expression.

Protect secrets and transport data securely

Use HTTPS for every production API endpoint. Redirecting HTTP to HTTPS helps, but sensitive data should never be accepted over an insecure connection. Configure TLS at the reverse proxy, load balancer, or application server, and make sure the application recognizes the original secure scheme when it runs behind a trusted proxy. Otherwise, redirects and secure-cookie behavior may be wrong.

Store passwords with a purpose-built adaptive hashing function such as Argon2, bcrypt, PBKDF2, or scrypt, using framework-supported configuration. Never encrypt passwords for later recovery. Plaintext passwords should never appear in logs, support exports, or temporary storage.

Keep signing keys, database passwords, API credentials, and encryption material out of source code and repository configuration. Inject them through controlled secret management or deployment mechanisms. Development and production secrets must differ. If a credential reaches version control, treat it as exposed: revoke or rotate it instead of simply deleting it in a later commit. Good secret handling belongs alongside the account and project protections covered in Digital Hygiene for Developers: Protect Accounts, Secrets, and Projects.

Use least-privilege credentials for databases and external services. The account used by an API should have access only to the tables, commands, and schemas it needs. A read-only reporting endpoint should not use a database identity that can alter a schema or delete production data.

Make failures useful without revealing internals

Clients need stable error responses. Attackers do not need stack traces, class names, SQL fragments, filesystem paths, dependency versions, or token-validation details. Define a consistent error format with a machine-readable code, an HTTP status, and a limited message that is safe to show to the client.

{
  "code": "VALIDATION_ERROR",
  "message": "One or more fields are invalid",
  "fields": {
    "displayName": "must not be blank"
  }
}

In Spring-based applications, a centralized exception handler can map validation failures, missing resources, access denials, and unexpected exceptions to predictable responses. Log full diagnostic context on the server with a correlation ID, but return a generic 500 Internal Server Error for unhandled faults. Keep detailed debugging features and development error pages disabled in production.

Authentication failures need similar care. Login endpoints should not reveal whether a specific email address exists; a generic “invalid credentials” response reduces account enumeration. For protected resources, use status codes consistently: 401 Unauthorized when authentication is missing or invalid, and 403 Forbidden when an authenticated identity lacks permission.

Limit abuse and account for expensive operations

Rate limiting does not replace authorization, but it reduces the impact of password guessing, token abuse, scraping, and accidental retry loops. Apply stricter limits to login, registration, password reset, verification, search, exports, and file-upload routes. Limits may be keyed by account, API key, IP address, or a combination. An IP-only limit can affect users on shared networks, while an account-only limit can be bypassed with many accounts.

Protect expensive endpoints with pagination, maximum page sizes, query-complexity limits, and asynchronous jobs for large exports or reports. Do not load unbounded result sets into memory. For endpoints that create money movements, records, or external side effects, support idempotency keys so a network retry does not duplicate an operation.

Use secure HTTP behavior and browser-aware controls

Set security headers at the API gateway or application layer where appropriate. A JSON API often benefits from Cache-Control: no-store on sensitive responses. Disable content sniffing with X-Content-Type-Options: nosniff. If browsers access the API, configure CORS narrowly by listing approved origins, methods, and headers instead of returning * for a credentialed API.

CORS is not authentication. It tells compliant browsers which cross-origin scripts may read responses; it does not stop direct HTTP clients from calling a public endpoint. Every protected operation still needs authentication and authorization.

Logging, monitoring, and dependency maintenance

Logs without context make incidents harder to investigate, but indiscriminate logging creates another source of data exposure. Record request IDs, authenticated subject IDs where appropriate, route names, response status, latency, authorization failures, and significant state changes. Exclude passwords, full tokens, session identifiers, authorization headers, payment data, and sensitive personal data. Mask values before logging instead of relying on every developer to remember later.

Review and alert on unusual authentication failures, sudden spikes in 403 responses, repeated validation failures, elevated server errors, permission changes, and unexpected administrative actions. Restrict access to logs and set a retention policy; logs are part of the system’s sensitive-data inventory.

Java applications also inherit risk from dependencies. Pin dependency versions, remove libraries that are no longer used, and review vulnerability reports from approved build and dependency-scanning tools regularly. Test upgrades in a controlled environment because security updates can change defaults or compatibility. Keep the JDK, framework, server container, and operating system on an aligned patch process rather than treating the application JAR as the only component that matters.

Test security as part of normal API testing

Security tests should run as repeatable checks in the same pipeline as functional tests. Use test accounts with distinct roles and ownership. Confirm that anonymous users cannot access protected routes, ordinary users cannot reach each other’s objects, and administrators can perform only documented administrative actions.

Run automated checks only against systems and environments you own or are authorized to test. For an ownership-sensitive endpoint, create a resource with account A, authenticate as account B, call the same route using A’s identifier, and verify that neither the response body nor the status behavior reveals private resource details.