ASP.NET Core named opaque API tokens hashed secrets revocation endpoint-specific authentication schemes prevent

TL;DR: give each token a human name and a two-part value, a public lookup id plus a high-entropy random secret part. Show the full value exactly once at creation and store only a SHA-256 or HMAC-SHA256 hash of the secret part, never the plaintext. Validate it on every request in its own named authentication scheme called ApiToken, checking expiry and revocation against the store each time, which is what makes revocation instant. Pin every protected endpoint to that one scheme with an authorization policy that names the scheme, so a valid cookie, JWT bearer credential or Windows identity can never fall through onto a token endpoint. Partition rate limiting by the token id claim, and record usage as batched per-token aggregates instead of writing a row on every request.

Verbatim problem (the search that created the source thread):

ASP.NET Core named opaque API tokens hashed secrets revocation endpoint-specific authentication schemes prevent bearer Windows authentication rate limiting usage aggregates security pitfalls

Symptoms this fixes: one shared API secret for every client that cannot be revoked per client, secrets stored in plaintext or reversibly encrypted in the database, a token endpoint that also quietly accepts the app default scheme, no per-client usage view, and no way to kill one leaked token without rotating everyone.

Steps

1. Use a named, two-part token format

Format the value as three underscore-separated pieces: the literal prefix tok, a public lookup id of about 12 random characters, and a secret part made from 32 random bytes encoded as base64url text. The owner also gives the token a name at creation, such as ci-deploy or partner-import, and that name plus the lookup id are safe to show in lists and logs forever. The secret part is not. Generate the random bytes only with RandomNumberGenerator from System.Security.Cryptography, never with System.Random and never derived from the name, the owner id or the current time.

Expected output: a token the owner can identify in a dashboard by name and lookup id without seeing anything usable as a credential. Success check: searching the database and the logs for the secret part returns nothing.

2. Store only the hash, plus lifecycle fields

Store one record per token with these fields: the record id, the owner id, the name, the public lookup id with a unique index, the hash bytes, the granted scopes as a delimited string, the creation time, an optional expiry time, a nullable revoked time, a last-used time, and a usage counter aggregate kept in a separate table (step 8). Hash the secret part, not the whole formatted string, so the lookup stays a plain indexed equality search. Use SHA-256 over the secret part: that is sound here only because the secret part carries about 256 bits of randomness, so there is nothing to dictionary-attack. Do not use a password hashing function for this; a slow password hash buys nothing against a high-entropy random value and taxes every request. Stronger option: compute an HMAC-SHA256 keyed with a server-held pepper from configuration or a key vault, so a database leak alone does not even yield hashes an attacker can test offline guesses against. Compare hashes with CryptographicOperations.FixedTimeEquals so the comparison time does not leak how many bytes matched.

static byte[] HashSecretPart(string secretPart, byte[] pepper)
{
    using (var hmac = new HMACSHA256(pepper))
    {
        return hmac.ComputeHash(Encoding.UTF8.GetBytes(secretPart));
    }
}

Never store the plaintext, never log the full presented value, and return the full value only in the creation response.

Expected output: the table holds hashes and metadata only. Success check: stealing a read-only copy of the table gives an attacker no value they can present to the API.

3. Issue tokens through an authenticated management endpoint only

Creation, listing and revocation are owner operations done with the app normal user sign-in, not with an API token itself, otherwise a leaked read-only token could mint itself a stronger successor. On creation: generate the value, insert the record from step 2, and return the full value once with a plain warning that it will not be shown again. Listing endpoints return name, lookup id, scopes, creation, expiry and last-used fields only.

Expected output: a new named token that works immediately and whose secret part exists only in the creation response and the client own store. Success check: re-opening the token list page shows the name and lookup id and no secret.

4. Validate in a dedicated ApiToken authentication handler

Write a custom handler deriving from AuthenticationHandler, registered under the single scheme name ApiToken, and make its HandleAuthenticateAsync do, in order: return NoResult when the Authorization header is absent or does not start with the scheme name ApiToken followed by a space; return Fail when the value does not split into the expected prefix, lookup id and secret part; look the record up by lookup id and return Fail when there is no record; return Fail when the revoked time is set or the expiry time has passed; hash the presented secret part as in step 2 and return Fail unless FixedTimeEquals matches the stored hash; otherwise build a ClaimsIdentity whose authentication type is ApiToken, with claims for the owner id, the token record id under a claim type named token_id, the token name, and one scope claim per granted scope, and return Success with a ticket for the ApiToken scheme. Reject values arriving in a query string outright; tokens in URLs land in logs, proxies and browser history.

Expected output: a valid, unrevoked token authenticates as an identity whose authentication type is ApiToken, and everything else fails closed. Success check: the same value sent under the Bearer scheme name gets a 401, because the handler only ever runs for its own scheme.

5. Prevent fallback to bearer, cookie or Windows authentication on token endpoints

This is the step most implementations miss. Do not register JwtBearer or Negotiate (Windows authentication) as a default scheme for the app, and do not leave token endpoints on a bare authorize attribute, which silently uses whatever default scheme exists, so a browser cookie or a domain identity can pass. Instead define one authorization policy per endpoint family that names the scheme explicitly. In policy terms: build the policy with AddAuthenticationSchemes called with ApiToken, plus RequireAuthenticatedUser, plus a scope requirement from step 6. Apply that named policy to the endpoints, with RequireAuthorization naming the policy in minimal APIs or the authorize attribute Policy property in MVC. If the same app genuinely needs Windows authentication or JWTs elsewhere, give those endpoints their own separate policies naming only their own schemes; never comma-combine schemes on a token endpoint, and never let a policy scheme with a forwarding selector forward an ApiToken request to another handler. Per Microsoft guidance on limiting identity by scheme, naming a single scheme means only that handler runs and identities from every other handler are ignored.

Expected output: each endpoint family accepts exactly one credential kind. Success check: calling a token endpoint with a valid app cookie, a valid JWT and a valid Windows identity each returns 401 or 403, and calling a Windows endpoint with a valid API token does the same.

6. Scope tokens per endpoint, not per app

Grant each token the smallest scope set, such as read or import, stored on the record and emitted as claims in step 4. Encode the requirement in the endpoint policy alongside the scheme from step 5, for example a policy named api-import that requires the ApiToken scheme and a scope claim equal to import, while api-read requires the read scope. A token that only reads must not be able to call an import or admin endpoint even though it authenticates fine.

Expected output: authentication proves which token this is, authorization decides what that token may do, endpoint by endpoint. Success check: a read-scoped token gets 403, not 401, on the import endpoint.

7. Revoke by setting the revoked time, and check it on every request

Revocation is a single update that sets the revoked time on the record, done by the owner from the management UI, with an audit entry naming who revoked which named token and when. Because the tokens are opaque and the handler reads the store on every request (step 4), revocation takes effect on the very next request; there is no signature to un-trust and no expiry window to wait out. That per-request store read is the deliberate price of opaque tokens. If you cache validation results to save database load, keep the cache lifetime to seconds, key the cache by lookup id, and evict the entry inside the revocation update, or revocation stops being instant and becomes a promise. Deleting the row also works and fails the lookup, but keeping the row with a revoked time preserves the audit and usage history.

Expected output: a revoked token gets 401 on its next call, while the owner other tokens keep working. Success check: revoke a token used by a test client and watch only that client start failing.

8. Rate limit per token and aggregate usage off the request path

Register the built-in rate limiting middleware with AddRateLimiter and a partitioned policy. Partition by the token_id claim from the authenticated identity, falling back to the remote IP address for anonymous calls, and give each partition a fixed window limiter, for example a permit limit per minute sized to the client plan. Place UseAuthentication before UseRateLimiter in the pipeline when the partition key comes from the user claims, and set the rejection status to 429. Separately, put a much lower IP-partitioned limit on the token creation and any sign-in endpoints to slow guessing. For usage: do not update the token row synchronously on every request, that makes one hot row per busy client. Instead, in the handler or a short middleware after successful authentication, enqueue a lightweight usage event carrying the token record id, the endpoint and the time onto a channel or queue, and let a background worker flush batched increments into a per-token per-hour aggregate table and update the last-used time only when it is older than a few minutes. Dashboards and quota checks read the aggregates, never the raw event stream.

Expected output: one abusive token hits its own 429s without touching other clients, and the owner can see calls per named token per hour. Success check: driving one token past its limit returns 429 for that token while a second token on the same IP range still succeeds.

9. Test the pitfalls before shipping

Pin these cases: (1) a valid token under the wrong scheme name fails; (2) a valid cookie, JWT or Windows identity on a token endpoint fails; (3) a revoked token and an expired token fail on the next request; (4) a token with the wrong scope gets 403 on a higher endpoint; (5) flipping one character in the secret part fails while the lookup id still resolves; (6) the creation response is the only place the full value ever appears, checked by grepping logs and the database for a known test value; (7) rate limiting bites per token, not per app.

Expected output: all seven pass. Success check: case 2 failing in either direction means a default or combined scheme is still configured somewhere, go back to step 5.

When this applies

• An ASP.NET Core API issues its own long-lived credentials to scripts, partners, CI jobs or devices, and needs per-client revocation.
• Clients are better identified by a name and scopes than by a user account, and usage per client matters for quotas or support.
• A leaked credential must be killable in seconds for one client without rotating a shared secret for everyone.
• The app also has interactive sign-in, cookies, JWTs or Windows authentication, and the API credential must not be confused with any of them.

When this does not apply

• Delegated user authorization across third parties. That is OAuth 2.0 and OpenID Connect territory; use an identity provider and JWT access tokens with introspection if revocation is needed, instead of hand-rolling a provider.
• Short-lived first-party browser sessions. Use the normal cookie authentication for those; opaque API tokens are for non-interactive callers.
• Purely internal service-to-service calls inside one trust boundary where managed identity or mutual TLS is available; those beat bearer-style credentials of any kind.
• Storing low-entropy secrets such as human-chosen passwords or short PIN-style codes. The fast-hash design in step 2 is only safe because the secret part is long and machine-generated.

Variant: the token also works as a JWT bearer credential

Same endpoints accept both because the default scheme is JwtBearer or the endpoint authorize lists both schemes. That is the fallback bug from step 5 in production form. Split the endpoints by policy so each names exactly one scheme, and if a migration period truly needs both, log which scheme authenticated each request and remove the extra scheme on a date.

Variant: revocation does not take effect

Almost always a validation cache: an earlier optimization cached successful lookups by lookup id with a long lifetime and the revocation update never evicts it. Shorten the lifetime to seconds, evict inside the revocation path, or drop the cache; the database read per request is the design, not a bug.

Variant: usage counts are wrong or the token table is a hotspot

Synchronous per-request row updates under-report on crashes and serialize busy clients onto one row. Move counting to the queued aggregate flush in step 8 and accept that dashboards lag by a flush interval; keep only the throttled last-used update on the token row itself.

Variant: timing differences reveal valid lookup ids

Looking up by lookup id is fine because the lookup id is not the secret, but returning different errors or measurably different timings for unknown id versus wrong secret part teaches an attacker which ids exist. Return one generic failure for both, and keep the FixedTimeEquals compare on the secret part from step 2; where the id does not exist, compare against a dummy hash so the work is similar.

Why it happens

JWTs and other signed tokens carry their proof inside themselves, so any service can validate them offline, and by the same token nobody can un-issue one before it expires. Opaque tokens invert that trade: the value is just a random pointer, all truth lives in the server store, so revocation, scoping changes and usage accounting are immediate, at the cost of a store read per request. The scheme confusion failures come from a different default in ASP.NET Core: authorization without a named scheme uses the app default, and an app with several handlers registered will happily authenticate an endpoint with whichever credential the caller happened to bring. Naming the scheme in the policy is what turns the endpoint from any-credential to this-credential-only.

Edge cases and pitfalls

• Name collisions: token names only need to be unique per owner, not globally; enforce that with a composite unique index on owner plus name if the UI promises it, and never use the name as a lookup key.
• Pepper rotation: rotating the HMAC pepper invalidates every stored hash at once. Version the hash with a key identifier stored on the record, verify with the matching pepper, and rehash lazily only when you still had the plaintext, which after creation you do not, so plan pepper rotation as a forced token reissue.
• Clock and expiry: compare expiry against UTC everywhere; a local-time comparison quietly extends or shortens token life by the server offset.
• Multiple instances: the built-in rate limiter counts per instance by default, so a per-token limit is effectively multiplied by the instance count behind a load balancer. Use a distributed limiter or a gateway limit when the number is a hard quota rather than a safety valve.
• Guessable lookup ids: the lookup id can be sequential-looking only if the secret part stays full-entropy and rate limiting guards the endpoint; making the id itself random costs nothing, so do that too.
• Tokens in telemetry: scrub the Authorization header from request logging and exception reports; one log pipeline that keeps headers undoes the hash-only storage design.
• Break-glass: keep an owner path to revoke all tokens for an account in one action for the day a client store leaks, and test it; per-token revoke alone is slow in an incident.