Skip to content
Clean GraphQL 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 cleangraphqlapi --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 -X POST "https://localhost:7331/graphql" -H "Authorization: Bearer eyJhbGciOi..." \
    -H "Content-Type: application/json" -d '{"query":"{ movies { totalCount } }"}'

    In Nitro, open the connection settings and add the token under Authentication.

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 cleangraphqlapi --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, [Authorize] on the queries and mutations, the Hot Chocolate authorization package, the ApplyPolicy enum in the schema snapshot, 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 protected fields answer with an error instead of data when the token is missing, from the wrong issuer or for the wrong audience. The HTTP status stays 200, because that’s how GraphQL does it.

    { "errors": [ { "message": "The current user is not authorized to access this resource.", "extensions": { "code": "AUTH_NOT_AUTHENTICATED" } } ] }
  • The version query needs one too. The schema, Nitro, /health/live and /health/ready stay open, so load balancers and curious humans can still check the lights are on.

  • 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, the normal authorization services and Hot Chocolate’s authorization. Every movie, author and review query, every mutation and the version query carry [Authorize]. 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-field policies are a short step from here: add policies to AddAuthorization and ask for them with [Authorize(Policy = "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.