Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

Security plays a vital role in REST API development. An insecure REST API can provide direct access to sensitive data on back-end systems. So, organizations need to pay attention to API Security. Spring Security provides various mechanisms to secure our REST APIs. One of them is API keys. An API key is a token that a client provides when invoking API calls. In this tutorial, we’ll discuss the implementation of API key-based authentication in Spring Security.

2. REST API Security

Spring Security can be used to secure REST APIs. REST APIs are stateless. Thus, they shouldn’t use sessions or cookies. Instead, these should be secure using Basic authentication, API Keys, JWT, or OAuth2-based tokens.

2.1. Basic Authentication

Basic authentication is a simple authentication scheme. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a Base64-encoded string username:password. Basic authentication is only considered secure with other security mechanisms such as HTTPS/SSL.

2.2. OAuth2

OAuth2 is the de facto standard for REST APIs security. It’s an open authentication and authorization standard that allows resource owners to give clients delegated access to private data via an access token.

2.3. API Keys

Some REST APIs use API keys for authentication. An API key is a token that identifies the API client to the API without referencing an actual user. The token can be sent in the query string or as a request header. Like Basic authentication, it’s possible to hide the key using SSL. In this tutorial, we focus on implementing API Keys authentication using Spring Security.

3. Securing REST APIs with API Keys

In this section, we’ll create a Spring Boot application and secure it using API key-based authentication.

3.1. Maven Dependencies

Let’s start by declaring the spring-boot-starter-security dependency in our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

3.2. Creating Custom Filter

The idea is to get the HTTP API Key header from the request and then check the secret with our configuration. In this case, we need to add a custom Filter in the Spring Security configuration class. We’ll start by implementing the GenericFilterBean. The GenericFilterBean is a simple javax.servlet.Filter implementation that is Spring-aware. Let’s create the AuthenticationFilter class:

public class AuthenticationFilter extends GenericFilterBean {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
      throws IOException, ServletException {
        try {
            Authentication authentication = AuthenticationService.getAuthentication((HttpServletRequest) request);
            SecurityContextHolder.getContext().setAuthentication(authentication);
            filterChain.doFilter(request, response);
        } catch (Exception exp) {
            HttpServletResponse httpResponse = (HttpServletResponse) response;
            httpResponse.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            httpResponse.setContentType(MediaType.APPLICATION_JSON_VALUE);
            PrintWriter writer = httpResponse.getWriter();
            writer.print(exp.getMessage());
            writer.flush();
            writer.close();
        }
    }
}

We only need to implement a doFilter() method. We evaluate the API Key header in this method and set the resulting Authentication object into the current SecurityContext instance. Then, the request is passed to the remaining filters for processing, routed to DispatcherServlet, and finally to our controller. If something goes wrong, we catch the Exception and write back to the caller without going forward with the filter chain. We delegate the evaluation of the API Key and constructing the Authentication object to the AuthenticationService class:

public class AuthenticationService {

    private static final String AUTH_TOKEN_HEADER_NAME = "X-API-KEY";
    private static final String AUTH_TOKEN = "Baeldung";

    public static Authentication getAuthentication(HttpServletRequest request) {
        String apiKey = request.getHeader(AUTH_TOKEN_HEADER_NAME);
        if (apiKey == null || !apiKey.equals(AUTH_TOKEN)) {
            throw new BadCredentialsException("Invalid API Key");
        }

        return new ApiKeyAuthentication(apiKey, AuthorityUtils.NO_AUTHORITIES);
    }
}

Here, we check whether the request contains the API Key header with a secret. If the header is null or isn’t equal to secret, we throw a BadCredentialsException. If the request has the header, it performs the authentication, adds the secret to the security context, and then passes the call to the following security filter. Our getAuthentication method is quite simple – we compare the API Key header and secret with a static value. To construct the Authentication object, we must use the same approach Spring Security typically uses to build the object using standard authentication. So, let’s extend the AbstractAuthenticationToken class and manually trigger authentication.

3.3. Extending AbstractAuthenticationToken

To successfully implement authentication for our application, we need to convert the incoming API Key to an Authentication object such as an AbstractAuthenticationToken. The AbstractAuthenticationToken class implements the Authentication interface, representing the secret/principal for an authenticated request. Let’s create the ApiKeyAuthentication class:

public class ApiKeyAuthentication extends AbstractAuthenticationToken {
    private final String apiKey;

    public ApiKeyAuthentication(String apiKey, Collection<? extends GrantedAuthority> authorities) {
        super(authorities);
        this.apiKey = apiKey;
        setAuthenticated(true);
    }

    @Override
    public Object getCredentials() {
        return null;
    }

    @Override
    public Object getPrincipal() {
        return apiKey;
    }
}

The ApiKeyAuthentication class is a type of AbstractAuthenticationToken object with the apiKey information obtained from the HTTP request. We use the setAuthenticated(true) method in the construction. As a result, the Authentication object contains apiKey and authenticated fields:

authentication

3.4. Security Config

We can register our custom filter programmatically by creating a SecurityFilterChain bean. In this case, we need to add the AuthenticationFilter before the UsernamePasswordAuthenticationFilter class using the addFilterBefore() method on an HttpSecurity instance. Let’s create the SecurityConfig class:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
      http.csrf(AbstractHttpConfigurer::disable)
          .authorizeHttpRequests(authorizationManagerRequestMatcherRegistry -> authorizationManagerRequestMatcherRegistry.requestMatchers("/**").authenticated())
          .httpBasic(Customizer.withDefaults())
          .sessionManagement(httpSecuritySessionManagementConfigurer -> httpSecuritySessionManagementConfigurer.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
          .addFilterBefore(new AuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }

}

Also, the session policy is set to STATELESS because we’ll use REST endpoints.

3.5. ResourceController

Last, we’ll create the ResourceController with a /home mapping:

@RestController
public class ResourceController {
    @GetMapping("/home")
    public String homeEndpoint() {
        return "Baeldung !";
    }
}

3.6. Disabling the Default Auto-Configuration

We need to discard the security auto-configuration. To do this, we exclude the SecurityAutoConfiguration and UserDetailsServiceAutoConfiguration classes:

@SpringBootApplication(exclude = {SecurityAutoConfiguration.class, UserDetailsServiceAutoConfiguration.class})
public class ApiKeySecretAuthApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApiKeySecretAuthApplication.class, args);
    }
}

Now, the application is ready to test.

4. Testing

We can use the curl command to consume the secured application. First, let’s try to request the /home without providing any security credentials:

curl --location --request GET 'http://localhost:8080/home'

We get back the expected 401 Unauthorized. Now let’s request the same resource, but provide the API Key and secret to access it as well:

curl --location --request GET 'http://localhost:8080/home' \
--header 'X-API-KEY: Baeldung'

As a result, the response from the server is 200 OK.

5. Conclusion

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.

Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

5 Comments
Oldest
Newest