StaffCoder
Spring Boot
Spring BootSpring Boot 4.1Java 25
12 modules · 48 challengesSign up
Module 7 · Security: Authentication & Authorization

API Key Issuer

medium—No data yet

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"
}

More in Security: Authentication & Authorization

See the module
Locker Room PIN AccessThis problem covers protecting a set of endpoints behind a username and password, while leaving the rest of the app open.—No data yetmediumNewsroom Editor PermissionsThis problem covers giving three accounts different powers over the same endpoints, and refusing the ones that lack permission.—No data yetmediumClinic Staff Role GateThis problem covers issuing a signed token at login and deciding what each request may reach from that token alone.—No data yetmedium

We use cookies that are necessary to run Staffcoder, and optional analytics cookies to see which pages get used. Analytics stays off unless you accept. Read our Cookie Policy.