Skip to content
Clean Minimal API
Lean Mean Clean Apps

Five templates, one brand, one search box. Everything in the docs is in here, including the bits we hoped you'd skim.

Try one of these

Results say which template they came from, so you won't end up reading about Lambda when you wanted GraphQL. Again.

Secure the API

Out of the box the API runs wide open, and there’s no authentication code in it at all. That’s lovely on a laptop and less lovely in production, so here’s how to close the door.

  1. Create the solution with --include-auth, and tell it who issues tokens and who they’re for:

    Terminal window
    dotnet new cleanminimalapi --name WorksOnMyMachine.Movies \
    --include-auth --authority https://login.example.com --audience https://movies.example.com

    --authority is required with --include-auth, so dotnet new stops and says so if it’s missing. To point each environment at its own server, override the settings in appsettings.json or with environment variables:

    Terminal window
    Authentication__Authority=https://login.example.com
    Authentication__Audience=https://movies.example.com
  2. Get a token from the authority for that audience, and send it.

    Terminal window
    curl "https://localhost:7311/api/movies" -H "Authorization: Bearer eyJhbGciOi..."

    Without a token, or with one from the wrong issuer or for the wrong audience, the API answers 401 Unauthorized.

Created the solution without --include-auth? The code isn’t hiding behind a setting, it isn’t there at all, so it goes in by hand. The quickest way to see every line is to let the template show you. Create a second solution with the same name and --include-auth next to yours, then compare the two:

Terminal window
dotnet new cleanminimalapi --name WorksOnMyMachine.Movies --output ../with-auth \
--include-auth --authority https://login.example.com --audience https://movies.example.com
git diff --no-index src ../with-auth/src
git diff --no-index tests ../with-auth/tests

Copy across what’s new: the Microsoft.AspNetCore.Authentication.JwtBearer package reference, the Authentication folder and its section in appsettings.json, the authentication regions in startup, RequireAuthorization() on each endpoint group, the bearer scheme for the OpenAPI document, and the authentication tests, so coverage stays where it was. The optional-token-auth skill in .agents/skills walks your coding agent through the same steps.

  • The movie, author and review endpoints need a valid token. GET /api/version needs one too. /health/live and /health/ready stay open, so load balancers and curious humans can still check the lights are on.
  • The OpenAPI document gains a Bearer security scheme, and Scalar gains an Authentication box beside the introduction. Pick Bearer under Select Auth Type, paste a token, and Send carries it on every request.
  • Tokens are validated against the authority’s published keys, so there’s no secret to store and nothing to rotate on your side.

AuthenticationSettings reads the Authentication section, and the API registers the JWT bearer handler and the normal authorization services. Every endpoint group calls RequireAuthorization(), the version endpoint included; only the health checks, the OpenAPI document and Scalar opt out. An empty authority still lets every request through, which is how the tests run, so make sure every environment you deploy to sets one.

Scopes, roles and per-endpoint policies are a short step from here: add policies to AddAuthorization and ask for them with RequireAuthorization("policy"). Which claims to check depends entirely on your identity provider, so the template stops at the door and lets you decide who gets past it.