Authorizing Requests

A validated token tells you who is calling. It does not tell you whether that caller may read employee 42, and nothing about the token can tell you, because the answer depends on the record.

So authorisation happens at two levels, and both are needed. The coarse level asks whether this caller may use this endpoint at all — a role, a scope, a policy. The record level asks whether this caller may touch this particular row. Endpoints that implement the first and skip the second are the most common serious flaw in real APIs, and the reason is understandable: the endpoint looks protected, because it is, at the level that is easy to see.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ReadEmployees", policy => policy
        .RequireAuthenticatedUser()
        .RequireClaim("scope", "employees.read"));
});

app.MapGet("/api/employees/{id:int}", async (
    int id, ClaimsPrincipal caller, EmployeeService employees, CancellationToken ct) =>
{
    var employee = await employees.FindAsync(id, ct);
    if (employee is null)
    {
        return Results.NotFound();
    }

    if (!int.TryParse(caller.FindFirstValue("employee_id"), out var callerId))
    {
        return Results.Forbid();
    }

    var mayRead =
        employee.Id == callerId
        || employee.ManagerId == callerId
        || caller.IsInRole("HumanResources");

    return mayRead
        ? Results.Ok(employee.ToResponse())
        : Results.Forbid();
})
.RequireAuthorization("ReadEmployees");

• RequireAuthorization("ReadEmployees") is the coarse level. A caller without the scope never reaches the handler, so the expensive work is not done for a request that was never allowed.
• The record-level check cannot be expressed there, because it needs the employee. That is why it sits inside the handler, immediately after the record is loaded and before anything is returned.
• callerId comes from the validated token's claims, via ClaimsPrincipal. It does not come from the route, the body or a header the caller controls — that distinction is the whole security property of this handler.
• TryParse rather than Parse: a token without the expected claim produces a refusal rather than an exception and a 500. Failing closed is the behaviour you want when the input to a security decision is missing.
• The three conditions are the rule in one readable expression: your own record, someone you manage, or an HR role. Written this way it can be reviewed, and the same expression belongs in a test.
• The response is a DTO, not the entity. A caller who may read a record still may not read every field of it.

One design decision has no universally right answer: when a record exists but this caller may not see it, do you return 403 or 404? A 403 is the accurate answer and it confirms the record exists, which is itself information. A 404 reveals nothing and is a small lie to a legitimate caller who now cannot tell a missing record from a forbidden one.

Use the sensitivity of existence to decide. That employee 42 exists in your company directory is not usually a secret, so 403 is fine and more helpful. That a particular medical record or a specific customer's invoice exists can be exactly the fact worth protecting, so 404 is the safer answer there.

Whichever you choose, apply it consistently across the API and document it. An API that returns 403 on some endpoints and 404 on others for the same situation tells a caller which records exist by the difference.