All 15 Authentication questions
More in Authentication
What is the difference between IAuthenticationService's SignInAsync/SignOutAsync methods and simply checking if a user 'is authenticated'? How does JWT bearer authentication validate an incoming token, and what claims does TokenValidationParameters check? How do external identity provider integrations (like Google or Microsoft Entra ID) work using OAuth/OpenID Connect authentication handlers? How do refresh tokens work alongside short-lived JWT access tokens, and how would you implement a refresh endpoint? How would you implement sign-out that properly invalidates both a cookie session and any associated server-side state? How does Windows Authentication (Negotiate/Kerberos) work in ASP.NET Core for intranet applications, and when is it appropriate? How would you implement passwordless authentication (like a magic link sent via email) in ASP.NET Core?
Advertisement
ASP.NET Core › Authentication

How do you implement API key authentication as a custom authentication scheme for machine-to-machine API access?

Advanced

Answer

Since API key authentication isn't a built-in ASP.NET Core scheme, you implement a custom AuthenticationHandler<TOptions> that extracts the key from a header or query parameter, validates it against a store (database, configuration, or cache), and constructs a ClaimsPrincipal representing the calling service/application if valid -- registered like any other scheme via AddScheme<TOptions, THandler>().
public class ApiKeyAuthHandler : AuthenticationHandler<ApiKeyAuthOptions> {
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync() {
        if (!Request.Headers.TryGetValue("X-Api-Key", out var key))
            return AuthenticateResult.Fail("Missing API key");
        var client = await _keyStore.ValidateAsync(key);
        if (client is null) return AuthenticateResult.Fail("Invalid API key");
        var identity = new ClaimsIdentity(new[] { new Claim("client", client.Name) }, Scheme.Name);
        return AuthenticateResult.Success(new AuthenticationTicket(new ClaimsPrincipal(identity), Scheme.Name));
    }
}
Real-world example A B2B integration platform issues each partner a unique API key validated by a custom authentication handler, letting partner-specific rate limits and permissions be enforced based on the resolved ClaimsPrincipal's client identity claim.

Common follow-ups: How does a custom AuthenticationHandler differ in complexity from using an existing scheme?;What are the security trade-offs of API keys versus OAuth client credentials?

Rate Limiting;Authorization
All 15 Authentication questions