Python FastAPI API key authentication with SHA-256 hash storage

<p>I need API key authentication for my FastAPI service. API keys must be stored securely (not plaintext), validated on every request, and I want to support multiple keys per user with revocation.</p>

<p>SHA-256 hash-based API key auth:</p> <div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">hashlib</span> <span class="kn">import</span><span class="w"> </span><span class="nn">secrets</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">HTTPException</span><span class="p">,</span> <span class="n">Header</span><span class="p">,</span> <span class="n">Depends</span> <span class="kn">from</span><span class="w"> </span><span class="nn">sqlalchemy</span><span class="w"> </span><span class="kn">import</span> <span class="n">select</span> <span class="n">API_KEY_PREFIX_LENGTH</span> <span class="o">=</span> <span class="mi">8</span> <span class="c1"># For display/lookup (non-secret prefix)</span> <span class="k">def</span><span class="w"> </span><span class="nf">generate_api_key</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span> <span class="w"> </span><span class="sd">"""Generate API key. Returns (raw_key, hashed_key)."""</span> <span class="n">raw</span> <span class="o">=</span> <span class="n">secrets</span><span class="o">.</span><span class="n">token_urlsafe</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span> <span class="c1"># 256 bits of randomness</span> <span class="n">hashed</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">(</span><span class="n">raw</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span> <span class="k">return</span> <span class="n">raw</span><span class="p">,</span> <span class="n">hashed</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_current_user</span><span class="p">(</span> <span class="n">x_api_key</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Header</span><span class="p">(</span><span class="n">alias</span><span class="o">=</span><span class="s1">'X-API-Key'</span><span class="p">),</span> <span class="n">db</span><span class="p">:</span> <span class="n">AsyncSession</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_db</span><span class="p">),</span> <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">User</span><span class="p">:</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">x_api_key</span><span class="p">:</span> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="mi">401</span><span class="p">,</span> <span class="s1">'API key required'</span><span class="p">)</span> <span class="c1"># Hash the provided key and look up:</span> <span class="n">key_hash</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">(</span><span class="n">x_api_key</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span> <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span> <span class="n">select</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">api_key_hash</span> <span class="o">==</span> <span class="n">key_hash</span><span class="p">)</span> <span class="p">)</span> <span class="n">user</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">scalar_one_or_none</span><span class="p">()</span> <span class="k">if</span> <span class="n">user</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="mi">401</span><span class="p">,</span> <span class="s1">'Invalid API key'</span><span class="p">)</span> <span class="k">return</span> <span class="n">user</span> <span class="n">CurrentUser</span> <span class="o">=</span> <span class="n">Annotated</span><span class="p">[</span><span class="n">User</span><span class="p">,</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_current_user</span><span class="p">)]</span> <span class="c1"># Registration endpoint:</span> <span class="nd">@router</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'/auth/register'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">register</span><span class="p">(</span><span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">):</span> <span class="n">raw_key</span><span class="p">,</span> <span class="n">hashed</span> <span class="o">=</span> <span class="n">generate_api_key</span><span class="p">()</span> <span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">email</span><span class="o">=</span><span class="n">email</span><span class="p">,</span> <span class="n">api_key_hash</span><span class="o">=</span><span class="n">hashed</span><span class="p">)</span> <span class="n">db</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">user</span><span class="p">)</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="c1"># Return raw key ONCE -- not stored, cannot be recovered:</span> <span class="k">return</span> <span class="p">{</span><span class="s1">'api_key'</span><span class="p">:</span> <span class="n">raw_key</span><span class="p">,</span> <span class="s1">'note'</span><span class="p">:</span> <span class="s1">'Save this -- it cannot be shown again'</span><span class="p">}</span> </code></pre></div> <p>Key points: - Never store raw API keys -- store SHA-256 hash only - Generate with secrets.token_urlsafe (cryptographically secure) - Index api_key_hash column for fast lookup - Return raw key only at generation time -- if lost, user must regenerate - Use compare_digest if doing manual comparison to prevent timing attacks</p>