index.html

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>python_jwt module &#8212; python-jwt 4.0.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/nature.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="#">python-jwt 4.0.0 documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">python_jwt module</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="python-jwt-module">
<h1>python_jwt module<a class="headerlink" href="#python-jwt-module" title="Permalink to this heading">¶</a></h1>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="#python_jwt.generate_jwt" title="python_jwt.generate_jwt"><code class="xref py py-obj docutils literal notranslate"><span class="pre">python_jwt.generate_jwt</span></code></a>(claims[, priv_key, ...])</p></td>
<td><p>Generate a JSON Web Token.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#python_jwt.process_jwt" title="python_jwt.process_jwt"><code class="xref py py-obj docutils literal notranslate"><span class="pre">python_jwt.process_jwt</span></code></a>(jwt)</p></td>
<td><p>Process a JSON Web Token without verifying it.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#python_jwt.verify_jwt" title="python_jwt.verify_jwt"><code class="xref py py-obj docutils literal notranslate"><span class="pre">python_jwt.verify_jwt</span></code></a>(jwt[, pub_key, ...])</p></td>
<td><p>Verify a JSON Web Token.</p></td>
</tr>
</tbody>
</table>
<span class="target" id="module-python_jwt"></span><p>Functions for generating and verifying JSON Web Tokens.</p>
<dl class="py function">
<dt class="sig sig-object py" id="python_jwt.generate_jwt">
<span class="sig-prename descclassname"><span class="pre">python_jwt.</span></span><span class="sig-name descname"><span class="pre">generate_jwt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">claims</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">priv_key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">algorithm</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'PS512'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lifetime</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expires</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">not_before</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">jti_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">16</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#python_jwt.generate_jwt" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate a JSON Web Token.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>claims</strong> (<em>dict</em>) – The claims you want included in the signature.</p></li>
<li><p><strong>priv_key</strong> (<a class="reference external" href="https://jwcrypto.readthedocs.io/en/latest/jwk.html">jwcrypto.jwk.JWK</a>) – The private key to be used to sign the token. Note: if you pass <code class="docutils literal notranslate"><span class="pre">None</span></code> then the token will be returned with an empty cryptographic signature and <code class="xref py py-obj docutils literal notranslate"><span class="pre">algorithm</span></code> will be forced to the value <code class="docutils literal notranslate"><span class="pre">none</span></code>.</p></li>
<li><p><strong>algorithm</strong> (<em>str</em>) – The algorithm to use for generating the signature. <code class="docutils literal notranslate"><span class="pre">RS256</span></code>, <code class="docutils literal notranslate"><span class="pre">RS384</span></code>, <code class="docutils literal notranslate"><span class="pre">RS512</span></code>, <code class="docutils literal notranslate"><span class="pre">PS256</span></code>, <code class="docutils literal notranslate"><span class="pre">PS384</span></code>, <code class="docutils literal notranslate"><span class="pre">PS512</span></code>, <code class="docutils literal notranslate"><span class="pre">ES256</span></code>, <code class="docutils literal notranslate"><span class="pre">ES384</span></code>, <code class="docutils literal notranslate"><span class="pre">ES512</span></code>, <code class="docutils literal notranslate"><span class="pre">HS256</span></code>, <code class="docutils literal notranslate"><span class="pre">HS384</span></code>, <code class="docutils literal notranslate"><span class="pre">HS512</span></code> and <code class="docutils literal notranslate"><span class="pre">none</span></code> are supported.</p></li>
<li><p><strong>lifetime</strong> (<em>datetime.timedelta</em>) – How long the token is valid for.</p></li>
<li><p><strong>expires</strong> (<em>datetime.datetime</em>) – When the token expires (if <code class="xref py py-obj docutils literal notranslate"><span class="pre">lifetime</span></code> isn’t specified)</p></li>
<li><p><strong>not_before</strong> (<em>datetime.datetime</em>) – When the token is valid from. Defaults to current time (if <code class="docutils literal notranslate"><span class="pre">None</span></code> is passed).</p></li>
<li><p><strong>jti_size</strong> (<em>int</em>) – Size in bytes of the unique token ID to put into the token (can be used to detect replay attacks). Defaults to 16 (128 bits). Specify 0 or <code class="docutils literal notranslate"><span class="pre">None</span></code> to omit the JTI from the token.</p></li>
<li><p><strong>other_headers</strong> (<em>dict</em>) – Any headers other than “typ” and “alg” may be specified, they will be included in the header.</p></li>
</ul>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>unicode</p>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>The JSON Web Token. Note this includes a header, the claims and a cryptographic signature. The following extra claims are added, per the <a class="reference external" href="http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html">JWT spec</a>:</p>
</dd>
</dl>
<ul class="simple">
<li><p><strong>exp</strong> (<em>IntDate</em>) – The UTC expiry date and time of the token, in number of seconds from 1970-01-01T0:0:0Z UTC.</p></li>
<li><p><strong>iat</strong> (<em>IntDate</em>) – The UTC date and time at which the token was generated.</p></li>
<li><p><strong>nbf</strong> (<em>IntDate</em>) – The UTC valid-from date and time of the token.</p></li>
<li><p><strong>jti</strong> (<em>str</em>) – A unique identifier for the token.</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p>ValueError: If other_headers contains either the “typ” or “alg” header</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="python_jwt.process_jwt">
<span class="sig-prename descclassname"><span class="pre">python_jwt.</span></span><span class="sig-name descname"><span class="pre">process_jwt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">jwt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#python_jwt.process_jwt" title="Permalink to this definition">¶</a></dt>
<dd><p>Process a JSON Web Token without verifying it.</p>
<p>Call this before <a class="reference internal" href="#python_jwt.verify_jwt" title="python_jwt.verify_jwt"><code class="xref py py-func docutils literal notranslate"><span class="pre">verify_jwt()</span></code></a> if you need access to the header or claims in the token before verifying it. For example, the claims might identify the issuer such that you can retrieve the appropriate public key.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>jwt</strong> (<em>str</em><em> or </em><em>unicode</em>) – The JSON Web Token to verify.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>tuple</p>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">(header,</span> <span class="pre">claims)</span></code></p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="python_jwt.verify_jwt">
<span class="sig-prename descclassname"><span class="pre">python_jwt.</span></span><span class="sig-name descname"><span class="pre">verify_jwt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">jwt</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pub_key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allowed_algs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iat_skew</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">datetime.timedelta(0)</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">checks_optional</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_not_implemented</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#python_jwt.verify_jwt" title="Permalink to this definition">¶</a></dt>
<dd><p>Verify a JSON Web Token.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>jwt</strong> (<em>str</em><em> or </em><em>unicode</em>) – The JSON Web Token to verify.</p></li>
<li><p><strong>pub_key</strong> – The public key to be used to verify the token. Note: if you pass <code class="docutils literal notranslate"><span class="pre">None</span></code> and <strong>allowed_algs</strong> contains <code class="docutils literal notranslate"><span class="pre">none</span></code> then the token’s signature will not be verified.</p></li>
<li><p><strong>allowed_algs</strong> (<em>list</em><em> or </em><em>NoneType</em><em> (</em><em>meaning an empty list</em><em>)</em>) – Algorithms expected to be used to sign the token. The <code class="docutils literal notranslate"><span class="pre">in</span></code> operator is used to test membership.</p></li>
<li><p><strong>iat_skew</strong> (<em>datetime.timedelta</em>) – The amount of leeway to allow between the issuer’s clock and the verifier’s clock when verifying that the token was generated in the past. Defaults to no leeway.</p></li>
<li><p><strong>checks_optional</strong> (<em>bool</em>) – If <code class="docutils literal notranslate"><span class="pre">False</span></code>, then the token must contain the <strong>typ</strong> header property and the <strong>iat</strong>, <strong>nbf</strong> and <strong>exp</strong> claim properties.</p></li>
<li><p><strong>ignore_not_implemented</strong> (<em>bool</em>) – If <code class="docutils literal notranslate"><span class="pre">False</span></code>, then the token must <em>not</em> contain the <strong>jku</strong>, <strong>jwk</strong>, <strong>x5u</strong>, <strong>x5c</strong> or <strong>x5t</strong> header properties.</p></li>
</ul>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>tuple</p>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">(header,</span> <span class="pre">claims)</span></code> if the token was verified successfully. The token must pass the following tests:</p>
</dd>
</dl>
<ul class="simple">
<li><p>Its header must contain a property <strong>alg</strong> with a value in <strong>allowed_algs</strong>.</p></li>
<li><p>Its signature must verify using <strong>pub_key</strong> (unless its algorithm is <code class="docutils literal notranslate"><span class="pre">none</span></code> and <code class="docutils literal notranslate"><span class="pre">none</span></code> is in <strong>allowed_algs</strong>).</p></li>
<li><p>If the corresponding property is present or <strong>checks_optional</strong> is <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>
<ul>
<li><p>Its header must contain a property <strong>typ</strong> with the value <code class="docutils literal notranslate"><span class="pre">JWT</span></code>.</p></li>
<li><p>Its claims must contain a property <strong>iat</strong> which represents a date in the past (taking into account <code class="xref py py-obj docutils literal notranslate"><span class="pre">iat_skew</span></code>).</p></li>
<li><p>Its claims must contain a property <strong>nbf</strong> which represents a date in the past.</p></li>
<li><p>Its claims must contain a property <strong>exp</strong> which represents a date in the future.</p></li>
</ul>
</li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p>If the token failed to verify.</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="indices-and-tables">
<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this heading">¶</a></h1>
<ul class="simple">
<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
<li><p><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></p></li>
<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
</ul>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="#">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">python_jwt module</a><ul>
<li><a class="reference internal" href="#python_jwt.generate_jwt"><code class="docutils literal notranslate"><span class="pre">generate_jwt()</span></code></a></li>
<li><a class="reference internal" href="#python_jwt.process_jwt"><code class="docutils literal notranslate"><span class="pre">process_jwt()</span></code></a></li>
<li><a class="reference internal" href="#python_jwt.verify_jwt"><code class="docutils literal notranslate"><span class="pre">verify_jwt()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>

  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/index.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="#">python-jwt 4.0.0 documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">python_jwt module</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2015, David Halls.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>