<!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>Third-party applications — FitTrackee 0.7.10 documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" /> <link rel="stylesheet" type="text/css" href="_static/css/fork-awesome.min.css" /> <link rel="stylesheet" type="text/css" href="_static/css/custom.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" /> <link rel="next" title="Installation" href="installation.html" /> <link rel="prev" title="Features" href="features.html" /> <meta charset='utf-8'> <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'> <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'> <meta name="apple-mobile-web-app-capable" content="yes"> <script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script> <script type="text/javascript" src="_static/js/jquery-fix.js"></script> <script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script> <script type="text/javascript" src="_static/bootstrap-sphinx.js"></script> </head><body> <div id="navbar" class="navbar navbar-default navbar-fixed-top"> <div class="container"> <div class="navbar-header"> <!-- .btn-navbar is used as the toggle for collapsed navbar content --> <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse"> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="index.html"> FitTrackee</a> <span class="navbar-text navbar-version pull-left"><b>0.7.10 </b></span> </div> <div class="collapse navbar-collapse nav-collapse"> <ul class="nav navbar-nav"> <li><a href="https://github.com/SamR1/FitTrackee">GitHub</a></li> <li class="dropdown globaltoc-container"> <a role="button" id="dLabelGlobalToc" data-toggle="dropdown" data-target="#" href="index.html">Docs <b class="caret"></b></a> <ul class="dropdown-menu globaltoc" role="menu" aria-labelledby="dLabelGlobalToc"><ul class="current"> <li class="toctree-l1"><a class="reference internal" href="features.html">Features</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Third-party applications</a></li> <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="cli.html">Command line interface</a></li> <li class="toctree-l1"><a class="reference internal" href="api/index.html">API documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting/index.html">Troubleshooting</a></li> <li class="toctree-l1"><a class="reference internal" href="changelog.html">Change log</a></li> </ul> </ul> </li> <li class="dropdown"> <a role="button" id="dLabelLocalToc" data-toggle="dropdown" data-target="#" href="#">Page <b class="caret"></b></a> <ul class="dropdown-menu localtoc" role="menu" aria-labelledby="dLabelLocalToc"><ul> <li><a class="reference internal" href="#">Third-party applications</a><ul> <li><a class="reference internal" href="#scopes">Scopes</a></li> <li><a class="reference internal" href="#flow">Flow</a></li> <li><a class="reference internal" href="#resources">Resources</a></li> </ul> </li> </ul> </ul> </li> <li> <a href="features.html" title="Previous Chapter: Features"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Features</span> </a> </li> <li> <a href="installation.html" title="Next Chapter: Installation"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Installation »</span> </a> </li> <li class="hidden-sm"> <div id="sourcelink"> <a href="_sources/apps.rst.txt" rel="nofollow">Source</a> </div></li> </ul> <form class="navbar-form navbar-right" action="search.html" method="get"> <div class="form-group"> <input type="text" name="q" class="form-control" placeholder="Search" /> </div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> </div> <div class="container"> <div class="row"> <div class="body col-md-12 content" role="main"> <section id="third-party-applications"> <h1>Third-party applications<a class="headerlink" href="#third-party-applications" title="Permalink to this heading">¶</a></h1> <p>(<em>new in 0.7.0</em>)</p> <p>FitTrackee provides a REST API (see <a class="reference external" href="api/index.html">documentation</a>) whose most endpoints require authentication/authorization.</p> <p>To allow a third-party application to interact with API endpoints, an <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749">OAuth2</a> client can be created in user settings (‘apps’ tab).</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>OAuth2 endpoints requiring authentication are not accessible by third-party applications (<a class="reference external" href="api/oauth2.html">documentation</a>), only by FitTrackee client (first-party application).</p> </div> <p>FitTrackee supports only <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1">Authorization Code</a> flow (with <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7636">PKCE</a> support). It allows to exchange an authorization code for an access token. The client ID and secret must be sent in the POST body. It is recommended to use PKCE to provide a better security.</p> <section id="scopes"> <h2>Scopes<a class="headerlink" href="#scopes" title="Permalink to this heading">¶</a></h2> <p>The following scopes are available:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">application:write</span></code>: grants write access to application configuration (only for users with administration rights),</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">profile:read</span></code>: grants read access to auth endpoints,</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">profile:write</span></code>: grants write access to auth endpoints,</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">users:read</span></code>: grants read access to users endpoints,</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">users:write</span></code>: grants write access to users endpoints,</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">workouts:read</span></code>: grants read access to workouts-related endpoints,</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">workouts:write</span></code>: grants write access to workouts-related endpoints.</p></li> </ul> </section> <section id="flow"> <h2>Flow<a class="headerlink" href="#flow" title="Permalink to this heading">¶</a></h2> <ul> <li><p>The user creates an App (client) on FitTrackee for a third-party application.</p> <figure class="align-default"> <img alt="OAuth2 client creation on FitTrackee" src="_images/fittrackee_screenshot-07.png" /> </figure> <div class="line-block"> <div class="line">After registration, the client id and secret are shown.</div> <div class="line">They must be stored in the 3rd-party application by the user.</div> </div> </li> <li><div class="line-block"> <div class="line">The 3rd-party app needs to redirect to FitTrackee, in order for the user to authorize the 3rd-party app to access user data on FitTrackee.</div> </div> <figure class="align-default"> <img alt="App authorization on FitTrackee" src="_images/fittrackee_screenshot-08.png" /> </figure> <div class="line-block"> <div class="line">The authorization URL is <code class="docutils literal notranslate"><span class="pre">https://<FITTRACKEE_HOST>/profile/apps/authorize</span></code>.</div> <div class="line">The required parameters are:</div> </div> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">client_id</span></code>: the client id displayed after registration</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">response_type</span></code>: <code class="docutils literal notranslate"><span class="pre">code</span></code>, since FitTrackee only supports Authorization Code flow.</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">scope</span></code>: scopes separated with space.</p></li> </ul> <div class="line-block"> <div class="line">and optional parameters:</div> </div> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">state</span></code>: unique value to prevent cross-site request forgery</p></li> </ul> <div class="line-block"> <div class="line">For PKCE, the following parameters are mandatory:</div> </div> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">code_challenge</span></code>: string generated from a code verifier</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">code_challenge_method</span></code>: method used to create challenge, for instance “S256”</p></li> </ul> <div class="line-block"> <div class="line">Example for PKCE:</div> <div class="line"><cite>https://<FITTRACKEE_HOST>/profile/apps/authorize?response_type=code&client_id=<CLIENT_ID>&scope=profile%3Aread+workouts%3Awrite&state=<STATE>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256</cite></div> </div> </li> <li><div class="line-block"> <div class="line">After the authorization, FitTrackee redirects to the 3rd-party app, so the 3rd-party app can get the authorization code from the redirect URL and then fetches an access token with the client id and secret (endpoint <a class="reference external" href="https://samr1.github.io/FitTrackee/api/oauth2.html#post--api-oauth-token">/api/oauth/token</a>).</div> <div class="line">Example of a redirect URL:</div> <div class="line"><cite>https://example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE></cite></div> </div> </li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p>OAuth2 support is implemented with <a class="reference external" href="https://docs.authlib.org/en/latest/">Authlib</a> library.</p> </div> <div class="admonition warning"> <p class="admonition-title">Warning</p> <div class="line-block"> <div class="line">If FitTrackee is running behind a proxy, the <code class="docutils literal notranslate"><span class="pre">X-Forwarded-Proto</span></code> header must be set.</div> <div class="line">For instance for <cite>nginx</cite>:</div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>proxy_set_header X-Forwarded-Proto $scheme; </pre></div> </div> </div> </section> <section id="resources"> <h2>Resources<a class="headerlink" href="#resources" title="Permalink to this heading">¶</a></h2> <p>Some resources about OAuth 2.0:</p> <ul class="simple"> <li><p><a class="reference external" href="https://www.oauth.com">OAuth 2.0 Simplified</a> by <a class="reference external" href="https://aaronparecki.com">Aaron Parecki</a> (example for <a class="reference external" href="https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/">authorization code flow with PKCE</a>)</p></li> <li><p><a class="reference external" href="https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html">Web App Example of OAuth 2 web application flow</a> with Requests-OAuthlib (python)</p></li> <li><p><a class="reference external" href="https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session">OAuth 2 Session</a> with Authlib (python)</p></li> <li><p><a class="reference external" href="https://codeberg.org/SamR1/ft-oauth-client">Minimal example of an application interacting with FitTrackee</a> (python)</p></li> </ul> </section> </section> </div> </div> </div> <footer class="footer"> <div class="container"> <p class="pull-right"> <a href="#">Back to top</a> </p> <p> © Copyright 2018 - 2022, SamR1 <a rel="me" href="https://fosstodon.org/@FitTrackee"><i class="fa fa-mastodon" aria-hidden="true"></i></a>. Last updated on Dec 21, 2022.<br/> Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/> </p> </div> </footer> </body> </html>