Problem statement
Implement the security layer of an API key vault: administrators issue and revoke per-client keys with a master key, and clients present an issued key to read their own profile.
Requirements
Every response described below is JSON; error responses carry a single error field with the exact message given. Callers hold no cookies or sessions: no response sets a cookie, every request is authenticated by its header alone, and built-in cross-site request forgery protection must not block any request.
Authentication
Every endpoint except GET / requires the caller to present a key in the X-API-Key request header; GET / stays open to everyone.
- If the header is missing or blank, respond 401 Unauthorized with error message: "Missing API key"
- If the header equals the master key (the value of the vault.master-key property in src/main/resources/application.properties, master-key-2026 by default), the caller is authenticated as an administrator
- If the header equals the key value of a stored, non-revoked issued key, the caller is authenticated as a client whose name is the key's owner
- Any other value (a key that was never issued, or one that has been revoked) is invalid: respond 401 Unauthorized with error message: "Invalid API key" (subject to the throttling rules below)
Throttling
Invalid-key attempts are counted in memory, per presented key value, across all endpoints.
- The first 5 attempts with a given invalid key value each get the 401 "Invalid API key" response
- From the 6th attempt with that same key value onward, respond 429 Too Many Requests with error message: "Too many attempts"
- A different invalid key value has its own independent counter and still gets 401 until its own 6th attempt
- Requests presenting a valid key are never counted and never throttled
- Requests without the header are never counted; they always get the 401 "Missing API key" response
Authorization
- The endpoints under /admin accept only the master key; a caller authenticated with an issued key gets 403 Forbidden with error message: "Forbidden"
- GET /profile accepts only an issued key; a caller authenticated with the master key gets 403 Forbidden with error message: "Forbidden"
Endpoints
POST /admin/keys
- Accept a JSON body with owner and validate it: if owner is missing, empty, or whitespace-only, respond 400 Bad Request with error message: "Owner must not be blank"; a rejected request must not store anything
- On a valid body, generate the key value on the server, store it as a non-revoked key for that owner, and respond 201 Created with key (the generated value) and owner
- The generated key value is at least 32 characters long, is not derived from the owner name, and differs on every issue
DELETE /admin/keys/{key}
- If no key with that value was ever issued, respond 404 Not Found with error message: "API key not found" and change nothing
- Otherwise mark the stored key revoked (the record is kept, not deleted) and respond 204 No Content with an empty body; revoking an already-revoked key also responds 204
- Revocation is immediate: the very next request presenting the revoked key is rejected as invalid
- Revoking a key never affects any other stored key
GET /profile
- Respond 200 OK with owner set to the owner name of the presented key
Components to implement
- SecurityConfig declares the security rules of the application: it registers the header check below so it runs for every request, opens GET /, restricts /admin/** to administrators and GET /profile to clients, and produces the 403 "Forbidden" JSON response for authenticated callers who reach a surface their key does not grant
- ApiKeyAuthenticationFilter performs the per-request header check described in Authentication and Throttling: it resolves X-API-Key to the authenticated caller (administrator for the master key, the key's owner for an issued key) or writes the matching 401/429 JSON response itself
- ThrottleTracker keeps the in-memory failure counters: recordFailure increments the counter of the given key value and returns its new count, reset clears every counter
- KeyAdminService owns key administration: issueKey stores and returns a new active key for an owner, revokeKey marks the stored key with the given value revoked and throws the provided not-found exception when no such key exists
Sample Requests & Responses
Expand to view details on sample requests and responses.
GET / with no X-API-Key header
Response (200 OK):
Backend server running on port 8000
POST /admin/keys with header X-API-Key: master-key-2026
Request:
{
"owner": "Rita Vale"
}
Response (201 Created):
{
"key": "72a707ae-06f9-4c03-8f83-9c194d85808b",
"owner": "Rita Vale"
}
GET /profile with header X-API-Key: 72a707ae-06f9-4c03-8f83-9c194d85808b
Response (200 OK):
{
"owner": "Rita Vale"
}
GET /profile with no X-API-Key header
Response (401 Unauthorized):
{
"error": "Missing API key"
}
GET /profile with header X-API-Key: ghost-key-0001 (never issued, attempts 1 through 5)
Response (401 Unauthorized):
{
"error": "Invalid API key"
}
GET /profile with header X-API-Key: ghost-key-0001 (attempt 6 with the same value)
Response (429 Too Many Requests):
{
"error": "Too many attempts"
}
GET /profile with header X-API-Key: master-key-2026
Response (403 Forbidden):
{
"error": "Forbidden"
}
POST /admin/keys with header X-API-Key: 72a707ae-06f9-4c03-8f83-9c194d85808b
Request:
{
"owner": "Eve Intruder"
}
Response (403 Forbidden):
{
"error": "Forbidden"
}
POST /admin/keys with header X-API-Key: master-key-2026
Request:
{
"owner": " "
}
Response (400 Bad Request):
{
"error": "Owner must not be blank"
}
DELETE /admin/keys/72a707ae-06f9-4c03-8f83-9c194d85808b with header X-API-Key: master-key-2026
Response (204 No Content): empty body
GET /profile with header X-API-Key: 72a707ae-06f9-4c03-8f83-9c194d85808b (the key revoked above)
Response (401 Unauthorized):
{
"error": "Invalid API key"
}
DELETE /admin/keys/never-issued-key-9999 with header X-API-Key: master-key-2026
Response (404 Not Found):
{
"error": "API key not found"
}
