API Key Management
Introduction & Lesson Overview
Welcome back! In the previous lessons, you learned how to generate secure API keys, store them safely, and use them to authenticate requests to your Spring Boot application. You also saw how to combine API key authentication with JWTs for flexible access control. Now that you have a solid foundation in creating and authenticating API keys, it is time to focus on managing them securely.
In this lesson, you will learn how to list your API keys in a way that protects sensitive information, how to revoke (deactivate) keys when they are no longer needed, and how to protect your API from abuse using rate limiting. These are essential skills for any real-world API, as they help you maintain security, support auditing, and prevent misuse. By the end of this lesson, you will be able to build robust API key management endpoints and understand how to integrate them into your Spring Boot application.
Listing API Keys Securely
When building an API key management system, it is important to allow users to view their keys — but you must never expose the full API key after it is created. This is a key security principle: if someone gains access to the list of keys, they should not be able to use them directly.
Let's look at how you can implement a secure listing endpoint. In the example below, the /api/api-keys/list route retrieves all API keys for the authenticated user. Instead of returning the full key, it provides a preview (just the prefix and asterisks), along with metadata such as the key's name, status, and expiration date.
In this code, the endpoint first fetches all API keys for the current user using the JPA repository method findByUserIdOrderByCreatedAtDesc(). This is a Spring Data JPA derived query method — Spring automatically generates the implementation based on the method name. The findByUserId part tells Spring to filter by the userId field, OrderBy sorts the results, CreatedAt specifies which field to sort by, and Desc means descending order (newest first). So this method returns all keys for the user, sorted from most recent to oldest.
For each key, the code calculates whether the key is expired and how many days remain until expiration using ChronoUnit.DAYS.between(). The keyPreview field is set to a string like pb_************************************************************, so the actual key value is never exposed. The status is set to expired, expiring_soon, or active based on the expiration date.
Notice the use of LinkedHashMap instead of HashMap for the response maps. This is important because LinkedHashMap preserves insertion order — the order in which you put items into the map. When Spring Boot converts these maps to JSON, the fields appear in the exact order they were added, making the API response predictable and easier to read. A regular HashMap would return fields in arbitrary order, which could confuse API consumers who expect consistent responses.
The response includes a list of keys with their metadata, as well as counts of total and active keys.
A sample response might look like this:
This approach allows users to manage their keys without risking exposure of sensitive information.
Secure API Key Revocation
Sometimes, you need to disable an API key — maybe it was leaked, or it is no longer needed. Instead of deleting the key from the database, it is best practice to deactivate it. This keeps an audit trail, which is important for security and compliance. Deactivated keys can no longer be used, but you still have a record of their existence and history.
Here is how you can implement a revocation endpoint:
In this code, the endpoint looks up the API key by its ID and the current user using the JPA repository. If the key is found, it sets isActive to false and saves the change to the database. The action is logged for auditing. The response confirms the revocation and includes the key's ID and name.
A typical response would be:
By deactivating rather than deleting, you ensure that you can always review which keys existed and when they were revoked.
Implementing Rate Limiting For API Key Requests
As your API grows, it is important to protect it from abuse. One common attack is to flood your API with requests, which can slow down or even crash your service. Rate limiting helps prevent this by restricting how many requests a user or API key can make in a given time period.
In Java/Spring Boot applications, you can use the Bucket4j library to implement rate limiting. In this example, you configure rate limiting to allow each API key 100 requests per hour. The filter checks if the request is authenticated with an API key and applies the limit accordingly. JWT and unauthenticated requests skip rate limiting entirely, as they typically represent interactive users who are less likely to abuse the API.
Here's how to implement the rate limiting filter:
The Bucket4j library automatically manages rate limiting state and calculates the remaining tokens. The ConcurrentHashMap stores a bucket for each API key ID, and the computeIfAbsent method ensures thread-safe bucket creation. Each bucket is configured with a bandwidth of 100 requests per hour using Bandwidth.simple().
The getRateLimitKey() method is the heart of the bypass logic. When a request comes in with API key authentication, it returns a key like api_key_123, which is stored in the buckets map and tracked across requests. For JWT or unauthenticated requests, it returns bypass_ followed by a random UUID. This works because each non-API-key request gets a unique key that has never been seen before. Since the key is unique, computeIfAbsent creates a fresh bucket with 100 available tokens, and the request immediately succeeds. The bucket is never reused because the next request will have a different UUID. This means JWT and unauthenticated requests effectively have no rate limit.
The security trade-off here is intentional: API keys are designed for automated, high-volume access where abuse is more likely, so they need strict limits. JWT authentication requires users to log in and is typically used for interactive sessions, making abuse less likely and rate limiting less necessary. However, be aware that this approach means unauthenticated endpoints are also unprotected from abuse — in a production system, you might want to apply IP-based rate limiting to public endpoints instead of skipping limits entirely.
When a client makes API key requests, they will see dynamic headers in the response:
These headers decrement with each request, showing the client exactly how many requests they have left and when the limit resets. If a user exceeds the limit, they receive a 429 error:
This helps protect your API from accidental or malicious overuse by automated systems using API keys, while providing clear, real-time feedback about usage limits through dynamic headers. JWT and unauthenticated requests bypass rate limiting entirely by using unique bypass keys that are never tracked.
Integrating Management Endpoints Into Spring Boot
Now that you have endpoints for listing and revoking API keys, and a rate limiting setup, you need to integrate them into your main Spring Boot application. This ensures that all API routes are protected and that key management is available to authenticated users.
Here is how the controller and filters are set up:
The rate limiting filter integrates automatically through Spring Boot's filter chain. Register the filter by adding a @Component annotation to the RateLimitFilter class, and Spring Boot will automatically apply it to all requests. The filter checks the authMethod and apiKeyId attributes that should be set by an authentication filter earlier in the chain.
This structure keeps your application organized and secure, ensuring that automated API access is protected by rate limiting while interactive users can work without restrictions.
Summary & Next Steps
In this lesson, you learned how to manage API keys securely in your Spring Boot application. You saw how to list API keys without exposing sensitive information, how to revoke keys safely for audit purposes, and how to protect your API from abuse using rate limiting that specifically targets API key requests while allowing interactive users unrestricted access. You also learned how to integrate these features into your main Spring Boot application for a clean and secure architecture.
These skills are essential for any API that uses key-based authentication. They help you keep your users safe, support compliance, and maintain the reliability of your service. In the next set of practice exercises, you will get hands-on experience with these concepts, reinforcing what you have learned and preparing you to build secure, production-ready APIs. Remember, on CodeSignal, all the necessary libraries are pre-installed, so you can focus on writing and testing your code. Good luck, and keep building your security skills!
