API Key Authentication in .NET Minimal APIs

In this article, I'll walk through implementing API key authentication for .NET Minimal APIs. We'll explore how to implement API key authentication in .NET Minimal APIs while supporting multiple API keys. For the purpose of this article we'll store the valid API keys in a single environment variable. We'll build a complete working example of a cat-related API but we'll implement a single GET endpoint to keep things simple.

Understanding API Key Authentication

API key authentication is a simple but effective method that allows us to control access to our APIs. The concept is straightforward: clients include a pre-shared key in their requests, and the server validates this key before processing the request.

The keys can be included in various ways such as request body, query string, or headers. In this example, we'll use the X-API-Key header to send the API key.

While API key authentication is not as robust as OAuth or JWT for complex scenarios,they are excellent for:

• Internal service-to-service communication
• Developer portals with limited public access
• Simple third-party integrations
• APIs that don't require user-specific permissions

Setting Up the Project

We'll start by creating a new .NET 9 Minimal API project:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
	app.MapOpenApi();
}

app.UseHttpsRedirection();

app.Run();

With this out of the way, let's move to our data class:

public class Cat
{
	public int Id { get; set; }
	public required string Name { get; set; }
	public required string Breed { get; set; }
	public required int Age { get; set; }
}

We create the Cat class with the properties Id, Name, Breed, and Age. The Id property is an integer that uniquely identifies each cat, while the other three properties are required and represent the cat's name, breed, and age.

Next, let's go back to our Program.cs file and add a list of cats to our API:

app.UseHttpsRedirection();

var cats = new List<Cat>
{
	new() { Id = 1, Name = "Whiskers", Breed = "Siamese", Age = 3 },
	new() { Id = 2, Name = "Mittens", Breed = "Persian", Age = 5 },
	new() { Id = 3, Name = "Felix", Breed = "Tabby", Age = 2 },
	new() { Id = 4, Name = "Shadow", Breed = "Maine Coon", Age = 4 },
	new() { Id = 5, Name = "Luna", Breed = "Ragdoll", Age = 1 }
};

app.Run();

We create a list of Cat objects with some sample data. This will serve as our in-memory database for the API.

Next, let's add a GET endpoint to retrieve the list of cats:

app.MapGet("/api/cats", () =>
{
	return Results.Ok(cats);
})
.WithName("GetAllCats")
.WithOpenApi();

Using the MapGet() method, we create a very rudimentary endpoint. It simply returns the list of cats in JSON format - we don't need anything more complex in our case. We also add a name and OpenAPI documentation for the endpoint.

If you are interested in learning more about Minimal APIs in general, or dive deeper into authentication and authorization, you can purchase my course here.

Creating The Key Components For API Key Authentication

We'll need several components in order for our solutions to properly implement key authentication. We start by creating the CATS_API_VALID_API_KEY environment variable and using 69ee6053-fd29-4f2c-8aef-7d11bdbd68a6,0e346492-5620-4ee5-9bbf-a6dbd146485d,d25172c1-1345-4645-9122-558ef81627d2 as its value. In a production environment, you would typically store this in a secure vault or configuration management system.

Let's create a way to validate our API keys:

public class ApiKeyAuthenticationFilter : IEndpointFilter
{
	private const string ApiKeyHeader = "X-Api-Key";
	private readonly HashSet<string> _validApiKeys =
		new(Environment.GetEnvironmentVariable("CATS_API_VALID_API_KEYS")?.Split(',')
		?? []);

	public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, 
        EndpointFilterDelegate next)
	{
		string? apiKey = context.HttpContext.Request.Headers[ApiKeyHeader];

		if (!IsApiKeyValid(apiKey))
		{
			return Results.Unauthorized();
		}

		return await next(context);
	}

	private bool IsApiKeyValid(string? apiKey)
	{
		if (string.IsNullOrWhiteSpace(apiKey))
		{
			return false;
		}

		return _validApiKeys.Contains(apiKey);
	}
}

We create the ApiKeyAuthenticationFilter class and implement the IEndpointFilter interface. Upon initialization, we retrieve the CATS_API_VALID_API_KEYS environment variable, split its value, and store it in the _validApiKeys field. We also define the ApiKeyHeader constant, which represents the name of the header that will contain the API key.

Then, we create the IsApiKeyValid(). It checks if the passed value is a valid API key. For the value to be valid, it must not be empty and it must match the values in the _validApiKeys field.

Once tis is done, we move on to the InvokeAsync() method. This method is called each time when our filter is executed. Inside the method, we try to retrieve the value of the X-Api-Key header from the request and store it in the apiKey variable. Then, we call the IsApiKeyValid() method to check if the API key is valid. If it is not valid, we return an Unauthorized result, otherwise, we call the next filter in the pipeline using await next(context).

The most important step is taken care of, now let's make sure we can easily re-use our filter. We can do this by creating an extension method:

public static class ApiKeyAuthenticationExtensions
{
	public static RouteHandlerBuilder RequireApiKeyAuthentication(
        this RouteHandlerBuilder routeBuilder)
	{
		return routeBuilder.AddEndpointFilter<ApiKeyAuthenticationFilter>();
	}
}

For this purpose, we create the ApiKeyAuthenticationExtensions class and mark it as static. Then, we create the RequireApiKeyAuthentication() method, which adds the ApiKeyAuthenticationFilter to the endpoint filter pipeline. This allows us to easily apply the filter to any endpoint we want.

Utilizing API Key Authentication

Now that we have our filter and extension method, we can apply the API key authentication to our GET endpoint:

app.MapGet("/api/cats", () =>
{
	return Results.Ok(cats);
})
.RequireApiKeyAuthentication()
.WithName("GetAllCats")
.WithOpenApi();

We do this by chaining the RequireApiKeyAuthentication() method to the definition of our endpoint. This ensures that the API key authentication filter is executed before processing the request.

Now, when a client makes a request to the /api/cats endpoint, the API key authentication filter will check if the provided API key is valid. If it is not valid, the client will receive a 401 Unauthorized response. If the API key is valid, the request will proceed to the endpoint handler, and the client will receive the list of cats.

Security Considerations

Always use HTTPS to protect API keys in transit, ensuring secure communication between clients and servers. For the key storage, consider using secure storage solutions in production environments to prevent unauthorized access. Implement a process for regularly rotating keys to minimize security risks and exposure in case of compromise. Additionally, be very caution when logging to ensure API key values are never recorded in application logs, reducing the risk of accidental leaks.

Conclusion

Implementing API key authentication in .NET Minimal APIs provides a straightforward yet effective way to secure your endpoints. While using IEndpointFilter offers a clean and reusable approach, it's not the only way to achieve this—you could also implement middleware or use custom authorization policies depending on your needs. By leveraging a reusable authentication filter, and enforcing best practices like HTTPS and key rotation, you can enhance security while keeping the implementation simple. While API keys are not a replacement for more advanced authentication methods like OAuth or JWT, they are well-suited for internal services and lightweight integrations. With these principles in place, you now have a solid foundation for building secure APIs that control access efficiently.