Security schemes

The Security course locked the cats API: staff sign in for a JWT, the guard bound with APP_GUARD refuses everything else, and now a partner integration gets a shared key for one statistics route. None of that is in the document. A reader sees POST /cats, tries it from the Swagger UI, gets a 401 and has no idea what to send. A generated client has no notion that some calls need a header. OpenAPI has a place for this: security schemes, declared once for the document, and security requirements, which say per operation which scheme it needs. Swagger UI turns them into an Authorize button that then sends the credential with every request that requires it.

Schemes, once

A scheme is a named way to authenticate: HTTP basic or bearer, an API key in a header, a query or a cookie, OAuth2 with its flows. The DocumentBuilder declares them under components.securitySchemes. The common ones have a method each:

new DocumentBuilder()
  .addBearerAuth()                 // "bearer": http, bearer, JWT
  .addBasicAuth()                  // "basic": http, basic
  .addCookieAuth('connect.sid')    // "cookie": apiKey in a cookie
  .addOAuth2()                     // "oauth2"

Each takes options (the scheme object, and a second argument to change the name). Anything else is addSecurity(name, scheme) with the raw scheme object, the docs' example being a hand-declared basic scheme:

.addSecurity('partner', { type: 'apiKey', in: 'query', name: 'key' })

Declaring a scheme says nothing about which operations use it. That is the second half.

Requirements, per operation

@ApiBearerAuth() on a method or a controller adds security: [{ bearer: [] }] to those operations; @ApiBasicAuth(), @ApiCookieAuth() and @ApiOAuth2(['scope']) do the same for their schemes, and @ApiSecurity('partner') for one you named. Put it where the guard is: on the controller when every route needs a token, on the methods when some are public. A route with no requirement is documented as open, which is a claim you should only make about routes the guard really lets through.

The document describes here as everywhere. @ApiBearerAuth() does not protect a route; the guard does. A route with the decorator and no guard is open with a lock icon on it, and a route with a guard and no decorator is a mystery 401. Keep the two together, and let the Security course's @Public() decorator mark the exceptions in both senses.

The exchange itself

A bearer token comes from somewhere, and that route deserves the most care in the document because it is the first one a reader calls. The credentials DTO wants @ApiProperty({ example }) on each field so the Swagger UI prefills something that works; the successful response wants a type (a small class with the token property, so the reader knows the key to read); the failure wants @ApiUnauthorizedResponse({ description }) saying it was the password, since that is the one 401 that is not about a missing token. A 401 that every protected route shares goes in addGlobalResponse, as lesson 3's 500 did.

Your task

The API has the JWT guard from the Security course, @Public() on the reads and on POST /auth/login, and a new ApiKeyGuard on GET /cats/stats that wants an x-shelter-key header. The document knows none of this.

1. Declare two schemes: the built-in bearer scheme, and shelter-key, an API key sent in the x-shelter-key header. Declare, for every operation, that a 401 means The token or key is missing, expired or wrong.
2. Mark the create, the delete and the profile as needing the bearer token, and the stats as needing the partner key.
3. Document the sign-in: username and password with the examples john and changeme, a 200 whose body is an AccessTokenDto described as The token; send it as Authorization: Bearer <token>, and a 401 Wrong username or password.

Then open the app in a new tab, press Authorize, paste a token from POST /auth/login, and watch the create succeed from the page.

When it fails

• components.securitySchemes is missing, though the operations have security: [{ bearer: [] }]: the decorators are there and addBearerAuth() is not. Swagger UI shows no Authorize button, because it has no scheme to ask for.
• The stats operation says security: [{ "shelter-key": [] }] but the scheme is named shelterKey: the name in @ApiSecurity() must match the one given to addSecurity() exactly; the document does not check.
• POST /cats answers 401 with the token pasted into Authorize: the scheme was declared as apiKey instead of with addBearerAuth(), so the UI sent the token in a header of the wrong name. The guard wants Authorization: Bearer <token>.
• /auth/login shows a SignInDto with no properties: the class has none of the @ApiProperty() decorators; lesson 1's rule applies to credentials too.

Remember

• Schemes are declared once in the builder (addBearerAuth, addBasicAuth, addCookieAuth, addOAuth2, or addSecurity for your own); requirements go on operations (@ApiBearerAuth, @ApiSecurity(name)).
• The name in the decorator must match the name of the scheme.
• The decorator documents; the guard enforces. Put them in the same places.
• Document the sign-in route best of all: examples in, a token model out, and the one 401 that means the password.