DEV Community: Fmaes

Refresh tokens in a .NET 10 Minimal API: rotation, reuse detection and revocation

Fmaes — Sat, 24 Oct 2026 16:08:28 +0000

Update: A reader pointed out that the conditional UPDATE only covers two refreshes that land at the same moment. A second tab refreshing a second later finds the token already revoked, takes the theft branch and logs the user out everywhere. The starter now has a configurable reuse leeway (10 seconds by default): reusing a rotated token within it returns 401 without revoking the session (see the change). Thanks again, @mehdimohseni82! The code below has been updated to include it.

In the previous posts of this series I've been building a free .NET 10 Minimal API starter: JWT authentication, per-user ownership, rate limiting and health checks.

Until now, login returned a single JWT that lasted 60 minutes. That has two problems:

It can't be revoked. If a token leaks, whoever has it keeps access for up to an hour, and "log out" only means the client forgets the token.
Shortening it hurts users. A 15-minute token without a way to renew it means logging in again every 15 minutes.

Refresh tokens solve both. In this post I'll go through the design I chose, the code, how I tested expiry without waiting a week, and a couple of mistakes I made on the way.

The code is in the repo: Fmaes2/dotnet-minimal-api-starter.

The design in one table

	Access token	Refresh token
Format	JWT (signed, self-contained)	Opaque random string
Lifetime	15 minutes	7 days
Sent to	Every protected endpoint	Only `/api/auth/refresh` and `/api/auth/logout`
Stored on the server	No	Yes, as a hash
Can be revoked	No (it just expires)	Yes

{
  "accessToken": "eyJhbGciOi...",
  "accessTokenExpiresAt": "2026-10-24T15:45:00Z",
  "refreshToken": "q3Zx...",
  "refreshTokenExpiresAt": "2026-10-31T15:30:00Z"
}

The access token stays stateless, so protected endpoints don't hit the database to validate it. The refresh token is the stateful part, and it's only checked once every 15 minutes.

Three rules on top of that:

Rotation: each refresh token can be used only once. Using it returns a new pair and invalidates the old token.
Reuse detection: if an already used token shows up again, assume it was stolen and revoke the whole session (with a short leeway, explained below).
Revocation: logout revokes the session; logout-all revokes every session of the user.

I return the refresh token in the response body. For browser SPAs an HttpOnly cookie is the usual recommendation, but it brings CSRF and CORS into the picture, so I left it for a future post.

Storage: hash it, like a password (but not quite)

public class RefreshToken
{
    public Guid Id { get; set; }
    public required string UserId { get; set; }
    public required string TokenHash { get; set; }
    public Guid FamilyId { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime ExpiresAt { get; set; }
    public DateTime? RevokedAt { get; set; }
    public Guid? ReplacedByTokenId { get; set; }

    public bool IsActive(DateTime utcNow) => RevokedAt is null && ExpiresAt > utcNow;
}

A few decisions worth explaining:

Only the hash is stored. A refresh token is a credential. If the database leaks, plain tokens would let an attacker log in as any user for a week. With hashes, the leak is useless.

SHA-256, not bcrypt. Password hashes are slow on purpose because passwords have little entropy and can be brute-forced. A refresh token is 64 random bytes (512 bits), so there's nothing to guess, and a fast hash is enough. It also has a nice side effect: SHA-256 is deterministic, so the lookup is just WHERE TokenHash = @hash on a unique index.

var plain = Base64Url.EncodeToString(RandomNumberGenerator.GetBytes(64));
var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(plain)));

FamilyId groups the tokens of one login. Every token issued by rotating inherits it. That's what makes "revoke the whole session" a single UPDATE.

DateTime, not DateTimeOffset. My integration tests use in-memory SQLite, and the EF Core SQLite provider can't translate DateTimeOffset comparisons to SQL. DateTime in UTC works on both SQLite and PostgreSQL (timestamptz), and Npgsql throws if a non-UTC DateTime sneaks in, so mistakes surface early.

Rotation and reuse detection

This is the core of the feature:

public async Task<IssuedRefreshToken?> RotateAsync(string token, CancellationToken ct)
{
    var now = time.GetUtcNow().UtcDateTime;
    var hash = Hash(token);

    var stored = await db.RefreshTokens.AsNoTracking()
        .SingleOrDefaultAsync(t => t.TokenHash == hash, ct);

    if (stored is null)
        return null;

    if (stored.RevokedAt is not null)
    {
        var elapsed = now - stored.RevokedAt.Value;
        var withinLeeway = stored.ReplacedByTokenId is not null
            && elapsed < TimeSpan.FromSeconds(_jwt.RefreshTokenReuseLeewaySeconds);

        if (withinLeeway)
        {
            // Probably another tab that sent the old token before seeing the new one.
            logger.LogInformation(
                "Rotated refresh token reused after {ElapsedSeconds:F1}s, within the {LeewaySeconds}s leeway. Family {FamilyId} kept.",
                elapsed.TotalSeconds, _jwt.RefreshTokenReuseLeewaySeconds, stored.FamilyId);
            return null;
        }

        // Someone is using a token that was already consumed: treat it as theft.
        logger.LogWarning(
            "Refresh token reuse detected after {ElapsedSeconds:F1}s. Revoking family {FamilyId}.",
            elapsed.TotalSeconds, stored.FamilyId);
        await RevokeFamilyAsync(stored.FamilyId, now, ct);
        return null;
    }

    if (stored.ExpiresAt <= now)
        return null;

    var (plain, replacement) = NewToken(stored.UserId, stored.FamilyId, now);

    await using var tx = await db.Database.BeginTransactionAsync(ct);

    // Conditional update: only one concurrent request can claim the old token.
    var claimed = await db.RefreshTokens
        .Where(t => t.Id == stored.Id && t.RevokedAt == null)
        .ExecuteUpdateAsync(s => s
            .SetProperty(t => t.RevokedAt, now)
            .SetProperty(t => t.ReplacedByTokenId, replacement.Id), ct);

    if (claimed == 0)
        return null;

    db.RefreshTokens.Add(replacement);
    await db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);

    return new IssuedRefreshToken(stored.UserId, plain, replacement.ExpiresAt);
}

Why reuse detection works. Imagine an attacker steals a refresh token. Now two parties have it: the real client and the attacker. Whoever uses it first gets a new pair. When the other one tries, the token is already revoked. The server can't tell which of the two is the attacker, so it revokes the whole family and both have to log in again. The real user is annoyed once; the attacker is locked out.

Why the leeway. The rule above has one problem: a second tab of the same user can also present the old token, simply because it sent its refresh before the first tab's response arrived. Without a leeway, that tab triggers reuse detection and logs the user out everywhere. So a rotated token reused within a few seconds of its rotation (Jwt:RefreshTokenReuseLeewaySeconds, 10 by default) gets 401 without revoking the family. Only rotated tokens qualify (ReplacedByTokenId is set); a token revoked by logout never does. The cost is that a theft inside that window goes undetected, although the old token still gives the attacker nothing. Both branches are logged with the elapsed seconds, so the default can be checked against real traffic.

Why the conditional update. Reading the token and then marking it as used is a classic race: two requests can both read it as active and both get a new pair. WHERE Id = @id AND RevokedAt IS NULL lets the database decide: only one UPDATE affects a row, the other gets 0 and returns 401. It needs no row version column, so it behaves the same on PostgreSQL and SQLite.

Why the transaction. Revoking the old token and inserting the new one must happen together. Without it, a failure on the insert would leave the user with a revoked token and no replacement.

Why AsNoTracking. ExecuteUpdateAsync runs SQL directly and bypasses the change tracker, so a tracked copy of the token would be stale. Not tracking it avoids that trap.

The endpoints

group.MapPost("/refresh", Refresh)
    .AddEndpointFilter<ValidationFilter<RefreshTokenRequest>>()
    .RequireRateLimiting(RateLimitingExtensions.AuthPolicy);

group.MapPost("/logout", Logout)
    .AddEndpointFilter<ValidationFilter<RefreshTokenRequest>>();

group.MapPost("/logout-all", LogoutAll).RequireAuthorization();

private static async Task<Results<Ok<AuthResponse>, UnauthorizedHttpResult>> Refresh(
    RefreshTokenRequest req, UserManager<IdentityUser> users, TokenService tokens,
    RefreshTokenService refreshTokens, CancellationToken ct)
{
    var rotated = await refreshTokens.RotateAsync(req.RefreshToken, ct);
    if (rotated is null)
        return TypedResults.Unauthorized();

    var user = await users.FindByIdAsync(rotated.UserId);
    if (user is null)
        return TypedResults.Unauthorized();

    var (access, accessExpires) = tokens.CreateToken(user);
    return TypedResults.Ok(new AuthResponse(access, accessExpires, rotated.Token, rotated.ExpiresAt));
}

Some details:

/refresh and /logout are anonymous: by the time the client calls them, the access token has probably expired. The refresh token itself identifies the session.
/refresh reloads the user instead of copying claims from the old token, so a changed email (or, later, roles) is picked up.
/logout always returns 204, even for unknown tokens. Different answers would let someone probe which tokens are valid.
/refresh reuses the existing auth rate limiting policy. Logout doesn't need it: brute-forcing a logout gains nothing.
The validator caps the token at 200 characters (a real one is 86), so nobody can make the server hash megabytes of input.

Don't forget `ClockSkew`

TokenValidationParameters.ClockSkew defaults to 5 minutes: a JWT is still accepted up to 5 minutes after it expires, to tolerate clock differences between servers. With a 60-minute token nobody notices. With a 15-minute token, it's 33% of extra lifetime for a token you can't revoke.

ClockSkew = TimeSpan.FromSeconds(30)

Testing expiry without waiting 7 days

The service gets the time from an injected TimeProvider instead of DateTime.UtcNow:

builder.Services.TryAddSingleton(TimeProvider.System);

TryAdd only registers it if nothing else did, which leaves room for the tests to swap it. With the Microsoft.Extensions.TimeProvider.Testing package, the expiry test moves the clock forward instead of waiting:

[Fact]
public async Task Refresh_WithExpiredToken_Returns401()
{
    var clock = new FakeTimeProvider(DateTimeOffset.UtcNow);
    using var app = factory.WithWebHostBuilder(b =>
        b.ConfigureTestServices(s => s.AddSingleton<TimeProvider>(clock)));
    var client = app.CreateClient();
    var login = await RegisterAndLoginAsync(client);

    clock.Advance(TimeSpan.FromDays(8));
    var response = await RefreshAsync(client, login.RefreshToken);

    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
}

ConfigureTestServices runs after Program.cs, and when a service is registered twice the container resolves the last one, so the fake clock wins.

The other tests cover rotation, reuse revoking the whole family, unknown and empty tokens, logout and logout-all.

One case I deliberately didn't test: two concurrent refreshes with the same token. The test factory shares a single in-memory SQLite connection, and SqliteConnection isn't meant to be used from several threads at once. The test could fail because of the connection rather than my code, which is the definition of a flaky test. Testing it properly needs a real PostgreSQL instance, for example with Testcontainers.

Mistakes I made along the way

1. A table called RefreshToken instead of RefreshTokens. I configured the entity in OnModelCreating but forgot the DbSet. The code that used db.RefreshTokens didn't compile, and when I looked at the migration I'd already generated, the table name was singular. EF Core names a table after the DbSet property; without one, it uses the class name. Since the branch wasn't pushed yet, I added the DbSet, removed the migration, generated it again and amended the commit.

2. A 500 on login. The new code was running, but the migration was still pending in my local database because MigrateOnStartup is off in Development. The response only said "An unexpected error occurred" (on purpose, the global handler doesn't leak details), and the real cause was in the Serilog output. dotnet ef migrations list showed the migration as (Pending), and dotnet ef database update fixed it. I added this to the README's troubleshooting section.

Breaking change

The login response changed from { token, expiresAt } to { accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt }, and the default access token lifetime went from 60 to 15 minutes. In Conventional Commits that's a feat!: with a BREAKING CHANGE: footer.

Known limitations

Access tokens can't be revoked: after logout they stay valid until they expire (15 minutes at most).
Reusing a rotated token within the reuse leeway (10 s by default) doesn't revoke the session, so a theft that happens inside that window goes undetected. The attacker gets nothing from the old token, but keeps the new one.
Every rotation extends the refresh token lifetime by 7 days, so there's no absolute session limit yet.
Expired and revoked tokens aren't cleaned up from the database yet.

What's next

Roles and policies. One thing I already know will bite: with MapInboundClaims = false (see part 2), IsInRole won't find the roles unless RoleClaimType is set in TokenValidationParameters.

If you have ideas or questions, open a Discussion in the repo or leave a comment here.

Liveness and readiness health checks in a .NET 10 Minimal API (with an EF Core database check)

Fmaes — Sat, 17 Oct 2026 17:42:08 +0000

The code lives in a public repo and is tested in CI.

Part 4 of the series about my free, MIT-licensed .NET 10 Minimal API starter. Previous parts: the base template, per-user ownership and rate limiting.

The starter had a /health endpoint that always answered ok. It told you the process was running, but not whether it could actually serve requests. This post splits it into two endpoints.

Liveness vs readiness

/health/live: "is the process alive?" It runs no checks. If the app answers, it is alive. An orchestrator uses this to decide whether to restart the container.
/health/ready: "can it handle traffic?" It also checks the database. An orchestrator or load balancer uses this to decide whether to send traffic to the instance.

Keeping them separate matters. If the database goes down and your liveness probe also checks it, the orchestrator will restart a perfectly healthy API in a loop and make things worse.

1. Register the checks

builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);

AddHealthChecks() turns on the health check system.
AddDbContextCheck<AppDbContext> tries to connect through your DbContext and reports Unhealthy if it can't.
The ready tag lets us pick this check only for the readiness endpoint.

AddDbContextCheck is not in the framework. It comes from Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore:

dotnet add StarterKit.Api package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

2. Map the two endpoints

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false // run no checks: if the app answers, it is alive
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
});

Predicate decides which checks each endpoint runs. They answer 200 Healthy or 503 Unhealthy, which is what Docker, Kubernetes and load balancers understand.

3. Testing it, including the failure case

[Fact]
public async Task Ready_returns_503_when_a_check_fails()
{
    var client = factory.WithWebHostBuilder(builder =>
        builder.ConfigureServices(services =>
            services.AddHealthChecks().AddCheck(
                "always-failing",
                () => HealthCheckResult.Unhealthy(),
                tags: ["ready"])))
        .CreateClient();

    var response = await client.GetAsync("/health/ready");
    Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);
}

Instead of shutting down a database in a test, I register an extra check that always fails and tagged ready. The test confirms a failing check turns into a 503. Two more tests check that live and ready return 200 against in-memory SQLite.

Gotchas I hit

Two almost identical package names. Microsoft.Extensions.Diagnostics.HealthChecks is already part of ASP.NET Core. The one you need for AddDbContextCheck is the ...HealthChecks.EntityFrameworkCore one. I installed the wrong one first.
Version downgrade error (NU1605). The new package pulled EF Core 10.0.13 while my project referenced 10.0.12. NuGet refuses to downgrade, so the build failed. The fix is to keep all EF Core and ASP.NET Core packages on the same version.
Test projects don't get implicit usings. AddHealthChecks needs using Microsoft.Extensions.DependencyInjection; in the test project, even though the API project doesn't need it.

Limitations

The database check opens a connection on every probe, so don't set the probe interval too aggressively.
The endpoints are public and only return Healthy / Unhealthy, without details. Don't expose detailed responses without authentication.
It only checks the database. If you add Redis, queues or external APIs, each one deserves its own check.

Try it

Next up: refresh tokens. If you'd rather see something else first, open a Discussion.

Rate limiting login and registration in a .NET 10 Minimal API (per IP, no extra packages)

Fmaes — Sat, 17 Oct 2026 16:35:29 +0000

The code lives in a public repo and is tested in CI.

This is part 3 of the series about my free, MIT-licensed .NET 10 Minimal API starter. In part 1 I covered the base template, and in part 2 I added per-user ownership of resources.

Today: protecting /register and /login from brute-force attempts with the rate limiter that ships with ASP.NET Core. No NuGet package needed.

What I wanted

Limit only the auth endpoints, not the whole API.
Limit per client IP, so one noisy client doesn't lock everyone out.
Return a proper 429 Too Many Requests with a Retry-After header and a ProblemDetails body.
Make the limits configurable from appsettings.json.
Keep the existing integration tests unaffected.

1. Options bound from configuration

public sealed class AuthRateLimitOptions
{
    public const string Section = "RateLimiting:Auth";
    public int PermitLimit { get; init; } = 5;     // requests allowed...
    public int WindowSeconds { get; init; } = 60;  // ...per window
}

This is a plain class that holds the two numbers. The defaults are 5 requests per 60 seconds, and anyone can override them in configuration.

2. The policy

public static class RateLimitingExtensions
{
    public const string AuthPolicy = "auth";

    public static IServiceCollection AddAuthRateLimiting(
        this IServiceCollection services, IConfiguration configuration)
    {
        var settings = configuration.GetSection(AuthRateLimitOptions.Section).Get<AuthRateLimitOptions>()
                       ?? new AuthRateLimitOptions();

        services.AddRateLimiter(options =>
        {
            options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

            options.AddPolicy(AuthPolicy, httpContext =>
                RateLimitPartition.GetFixedWindowLimiter(
                    httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown",
                    _ => new FixedWindowRateLimiterOptions
                    {
                        PermitLimit = settings.PermitLimit,
                        Window = TimeSpan.FromSeconds(settings.WindowSeconds),
                        QueueLimit = 0
                    }));

            options.OnRejected = async (context, ct) =>
            {
                if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
                {
                    context.HttpContext.Response.Headers.RetryAfter =
                        ((int)Math.Ceiling(retryAfter.TotalSeconds)).ToString(CultureInfo.InvariantCulture);
                }

                await context.HttpContext.Response.WriteAsJsonAsync(new ProblemDetails
                {
                    Status = StatusCodes.Status429TooManyRequests,
                    Title = "Too many requests. Try again later."
                }, ct);
            };
        });

        return services;
    }
}

What each piece does:

AddPolicy registers a named policy. Endpoints opt in by name, so everything else stays unlimited.
RateLimitPartition.GetFixedWindowLimiter creates one independent counter for each partition key. Using the IP as the key gives you one bucket per client.
QueueLimit = 0 means that excess requests get a 429 right away instead of waiting.
OnRejected sets the Retry-After header and writes a ProblemDetails response, so the error looks like every other error in the API.

3. Wiring it up

builder.Services.AddAuthRateLimiting(builder.Configuration);

// ...
app.UseHttpsRedirection();
app.UseRateLimiter();      // before authentication
app.UseAuthentication();
app.UseAuthorization();

Then I opt the two endpoints in:

group.MapPost("/register", Register)
    .AddEndpointFilter<ValidationFilter<RegisterRequest>>()
    .RequireRateLimiting(RateLimitingExtensions.AuthPolicy);

group.MapPost("/login", Login)
    .AddEndpointFilter<ValidationFilter<LoginRequest>>()
    .RequireRateLimiting(RateLimitingExtensions.AuthPolicy);

UseRateLimiter() goes before UseAuthentication() so that abusive requests are rejected before any password hashing happens.

4. Testing it without breaking the other tests

Every integration test calls /register and /login, so a limit of 5 per minute would make the whole suite flaky. My ApiFactory (the shared WebApplicationFactory) raises the limit:

builder.UseSetting("RateLimiting:Auth:PermitLimit", "1000");

A dedicated factory then lowers it to 3 for the one test that checks the limiter itself:

builder.UseSetting("RateLimiting:Auth:PermitLimit", "3");

[Fact]
public async Task Login_is_rate_limited_after_too_many_attempts()
{
    var body = new { email = "nobody@test.com", password = "Wrong1234!" };

    for (var i = 0; i < 3; i++)
    {
        var allowed = await _client.PostAsJsonAsync("/api/auth/login", body);
        Assert.Equal(HttpStatusCode.Unauthorized, allowed.StatusCode);
    }

    var blocked = await _client.PostAsJsonAsync("/api/auth/login", body);

    Assert.Equal(HttpStatusCode.TooManyRequests, blocked.StatusCode);
    Assert.NotNull(blocked.Headers.RetryAfter);
}

The tests run in CI like everything else, and I also checked the 429 by hand with the .http file.

Limitations

This setup is intentionally simple, and you should know where it stops:

Behind a reverse proxy (nginx, a cloud load balancer), RemoteIpAddress is the proxy's IP unless you configure UseForwardedHeaders. Otherwise all your users share one bucket.
The counters live in memory, per instance. If you scale to several instances, each one counts separately. For that you'd need a distributed approach (e.g. Redis).
It limits by IP, not by account. Someone spreading attempts across many IPs is not stopped. A per-account lockout is on my list.

Try it

Next up: a /health endpoint that checks the database, and refresh tokens. If you have feedback or want something covered, open a Discussion.

Per-user ownership in a .NET Minimal API (and how the user reaches your endpoint)

Fmaes — Fri, 16 Oct 2026 17:14:26 +0000

Update: A reader pointed out that the sub / NameIdentifier split comes from MapInboundClaims on JwtBearerOptions, which defaults to true. Setting it to false keeps the raw JWT claim names, so GetRequiredUserId no longer needs the fallback. The starter now does exactly that (see the change). Thanks, @mehdimohseni82 ! The explanation below still describes the default behavior.

In the first post I shared a .NET 10 starter template and listed what it doesn't do yet. The biggest item on that list was this: any authenticated user could update or delete any product. This post is about fixing that, and about a question I had along the way: how does my endpoint know who the user is?

Repo: https://github.com/Fmaes2/dotnet-minimal-api-starter

The rule

Any authenticated user can read products.
Only the owner can update or delete a product.
Anyone else gets 403 Forbidden.

1. Store the owner

The product gets an OwnerId, and the database enforces it with a foreign key to the Identity users table:

public class Product
{
    // ...
    public string OwnerId { get; set; } = "";
}

modelBuilder.Entity<Product>(e =>
{
    // ...
    e.HasOne<IdentityUser>()
        .WithMany()
        .HasForeignKey(p => p.OwnerId)
        .IsRequired()
        .OnDelete(DeleteBehavior.Cascade);
});

The id is a string because IdentityUser uses a string key (a GUID). IsRequired() means a product can't be saved without an owner, so forgetting to set it fails loudly instead of silently.

2. How does the endpoint know who the user is?

Here is what actually happens on a request with an Authorization: Bearer <token> header:

app.UseAuthentication() runs before any endpoint. It calls the JWT bearer handler.
The handler reads the header, validates the token (signature, issuer, audience, expiry) and builds a ClaimsPrincipal from the token's claims.
That principal is stored in HttpContext.User. No header, or an invalid token, leaves the user anonymous.
app.UseAuthorization() checks RequireAuthorization() and rejects anonymous users with 401 before your handler runs.
When a handler declares a ClaimsPrincipal user parameter, Minimal APIs fills it with HttpContext.User. It doesn't come from the body or the query string.

So your endpoint never reads the header. It just receives what the middleware prepared, which also means the same handler would work unchanged if you switched to cookie authentication.

To read the id from the principal I added a small extension method:

public static string GetRequiredUserId(this ClaimsPrincipal user) =>
    user.FindFirst(ClaimTypes.NameIdentifier)?.Value
    ?? user.FindFirst(JwtRegisteredClaimNames.Sub)?.Value
    ?? throw new InvalidOperationException("The authenticated user has no id claim.");

Depending on the handler configuration, the id can show up as sub or as NameIdentifier, so it checks both. If neither exists it throws: endpoints require authentication and the tokens always carry sub, so that would be a programming error, not a client error.

3. Check the owner in the endpoints

On create, the owner comes from the token, never from the request body. The request type doesn't even have an owner field, so nobody can create a product in someone else's name.

On update and delete:

var product = await db.Products.FindAsync(id);
if (product is null) return TypedResults.NotFound();
if (product.OwnerId != user.GetRequiredUserId()) return TypedResults.Forbid();

Why 403 and not 404? Because any authenticated user can already read every product, so the fact that it exists is not a secret. If reads were private, I'd return 404 for other people's products so the API doesn't reveal which ids exist.

The handler's return type is a Results<Ok<...>, NotFound, ForbidHttpResult> union, so OpenAPI documents all three responses and the compiler complains if a case is not handled.

4. Testing with two users

The tests that matter use two users at once:

[Fact]
public async Task Another_user_cannot_update_a_product_they_do_not_own()
{
    var owner = CreateClientFor(await RegisterAndLoginAsync());
    var intruder = CreateClientFor(await RegisterAndLoginAsync());
    var id = await CreateProductAsync(owner);

    var response = await intruder.PutAsJsonAsync($"/api/products/{id}",
        new ProductRequest("Hacked", null, 1m));

    Assert.Equal(HttpStatusCode.Forbidden, response.StatusCode);

    var current = await owner.GetFromJsonAsync<ProductResponse>($"/api/products/{id}");
    Assert.Equal("Original", current!.Name);
}

The last two lines are the important part. Checking the status code alone would pass even if the API rejected the request after saving the change. Reading the product back proves it was not modified. There's an equivalent test for delete.

Bonus: `GET /api/auth/me`

While I was at it, I added an endpoint that returns the id and email of the authenticated user. It reads everything from the token claims and doesn't touch the database. It's also a handy way to see exactly what is in your token.

Gotchas

The migration adds a required column, so a database that already contains products can't take it as is. In development I recreated the database; in a real project you'd backfill an owner first.
Listing still returns everyone's products. Making each user see only their own is a different decision, and I haven't made it yet.
There are no roles yet, so no admin can edit other people's products.

What's next

Rate limiting on the login endpoint is next on my list. If you'd rather see something else first (refresh tokens, roles, a health check that actually checks the database), tell me in the comments or in the Discussions.

A .NET 10 Minimal API starter, so you can skip the boilerplate

Fmaes — Mon, 12 Oct 2026 15:59:05 +0000

Starting a new .NET API means spending hours on the same setup before you write the first useful line: authentication, error handling, validation, logging, Docker, tests and CI. I got tired of repeating it on every project, so I packaged it into a template and put it on GitHub for anyone who wants to skip that part.

Repo: https://github.com/Fmaes2/dotnet-minimal-api-starter

Who is this for?

People learning ASP.NET Core who want a small, working API to read, run and modify instead of starting from an empty project.
Developers who want to spin up a small side project quickly without rebuilding the same foundation again.

It's a starting point and a learning reference, not a production-ready base. More on that below.

What's inside

Minimal APIs organized by feature with MapGroup
ASP.NET Core Identity with JWT authentication
EF Core with PostgreSQL, migrations and paginated endpoints
FluentValidation through a reusable endpoint filter
Global error handling with ProblemDetails
Serilog logging to console and file
Unit and integration tests (xUnit, Moq, in-memory SQLite)
Dockerfile and docker-compose with a database healthcheck
GitHub Actions CI

A few decisions worth mentioning

Minimal APIs, but not a giant Program.cs. Each feature lives in its own file with an extension method, and a route group takes care of the shared pieces:

var group = app.MapGroup("/api/products")
    .WithTags("Products")
    .RequireAuthorization();

group.MapPost("/", Create).AddEndpointFilter<ValidationFilter<ProductRequest>>();

The group applies the route prefix, the OpenAPI tag and the authorization requirement to every endpoint inside it, and the filter validates the request body before the handler runs.

Integration tests that don't need Docker. They run against in-memory SQLite, so dotnet test works on a fresh machine. The trade-off is that SQLite and PostgreSQL differ in small details, and the README says so.

Try it

docker compose up --build

The README covers the local development flow too, and how to add your own entity by copying the products feature. The repo is MIT licensed and marked as a template, so you can use the Use this template button.

What it's not (yet)

I'd rather tell you now than have you find out later:

Update: product ownership is now implemented. Read how it works in the second post.

Anyone can register, and login attempts aren't limited. There's no lockout or rate limiting.

Tokens last 60 minutes with no refresh or revocation.

/health always answers "ok" without checking the database.

Endpoints talk to the DbContext directly. That's fine for a simple CRUD, but you'll want more structure as the business logic grows.

What would you add?

I'm deciding what to build next. If you've set up a .NET API recently, what took you the most time? Refresh tokens, roles, ownership checks, multi-tenancy, something else? Tell me in the comments or open a Discussion.

DEV Community: Fmaes

Refresh tokens in a .NET 10 Minimal API: rotation, reuse detection and revocation

The design in one table

Storage: hash it, like a password (but not quite)

Rotation and reuse detection

The endpoints

Don't forget ClockSkew

Testing expiry without waiting 7 days

Mistakes I made along the way

Breaking change

Known limitations

What's next

Liveness and readiness health checks in a .NET 10 Minimal API (with an EF Core database check)

Liveness vs readiness

1. Register the checks

2. Map the two endpoints

3. Testing it, including the failure case

Gotchas I hit

Limitations

Try it

Rate limiting login and registration in a .NET 10 Minimal API (per IP, no extra packages)

What I wanted

1. Options bound from configuration

2. The policy

3. Wiring it up

4. Testing it without breaking the other tests

Limitations

Try it

Per-user ownership in a .NET Minimal API (and how the user reaches your endpoint)

The rule

1. Store the owner

2. How does the endpoint know who the user is?

3. Check the owner in the endpoints

4. Testing with two users

Bonus: GET /api/auth/me

Gotchas

What's next

A .NET 10 Minimal API starter, so you can skip the boilerplate

Who is this for?

What's inside

A few decisions worth mentioning

Try it

What it's not (yet)

What would you add?

Don't forget `ClockSkew`

Bonus: `GET /api/auth/me`