Fixing OpenAPI Transform for Scalar to Add a Global Auth Token in .NET 10

Introduction

In my previous article, I explained how to use Scalar UI with a .NET 9 Web API and add a global JWT authorization scheme. The goal was to avoid putting [Authorize] on every endpoint and instead configure the OpenAPI document so Scalar UI would show a global authentication input.

After upgrading to .NET 10, the same code no longer works. Instead of compiling, the project throws errors about missing types and properties in the OpenAPI API.

What Changed in .NET 10

When .NET 10 shipped, Microsoft updated Microsoft.AspNetCore.OpenApi and related OpenAPI classes.

In .NET 9, the security scheme could be referenced like this:

new OpenApiSecurityScheme
{
    Reference = new OpenApiReference
    {
        Id = "Bearer",
        Type = ReferenceType.SecurityScheme
    }
}

That pattern worked because the OpenAPI model allowed a Reference object to be assigned directly to the security scheme.

In .NET 10, that property and some internal types changed. The older pattern is no longer valid, so the compiler can no longer find:

Reference on OpenApiSecurityScheme
The Models namespace under Microsoft.OpenApi
Types expected by the older code

That is why the project fails with errors such as:

OpenApiSecurityScheme does not contain a definition for Reference

The type or namespace name Models does not exist

Cannot implicitly convert type ...

This does not mean the idea was wrong. The OpenAPI internal API changed, so the transformer must now use the updated APIs to build references.

OpenAPI type mismatch

How I Solved It

The fix was to rewrite the transformer to use the new OpenAPI reference APIs introduced with .NET 10.

Instead of assigning a Reference property directly on the security scheme, the new implementation:

Creates a proper OpenApiSecurityScheme object
Adds it to the document components using the AddComponent helper
Builds a security requirement that references the scheme in the document
Applies the requirement to all operations in the API

This produces a valid Bearer JWT scheme in the OpenAPI document, and Scalar UI can then read it and show a global token input.

Solution

Fixed Scalar auth token setup

Fixed OpenAPI transform

Conclusion

Upgrading to .NET 10 can cause confusing errors because the internal OpenAPI APIs changed. The old pattern of assigning Reference directly on security schemes no longer works. The correct fix is to use the new APIs for adding components and building references.

If you are upgrading from .NET 9 to .NET 10 and using Scalar UI with JWT authentication, this approach should make the transition smoother.

The original article links to the source code on GitHub: ScalarUiWithDotNet.

Thank you for reading.