Authenticating API Calls - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/5QFFR1798N4A/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/5QFFR1798N4A/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>When making calls to the API you’ll need to pass an access token in order to authenticate as a user. Vanilla has core support for access tokens, with the following features:</p><ul><li>Access tokens can be issued, verified, and revoked with the <strong>AccessTokenModel</strong></li><li>An access token submitted in the <strong>Authorization</strong> header will authenticate the appropriate user.</li><li>Expired access tokens are automatically pruned from the access token table, but stick around for a bit to give appropriate expired errors.</li></ul><h2 data-id="issuing-access-tokens">Issuing Access Tokens</h2><p>There isn’t a built-in user interface for issuing access tokens (yet). Right now, addons are expected to issue access tokens as part of their specific single-sign-on mechanism. You can create and issue access tokens with the <strong>AccessTokenModel</strong>. The <strong>AccessTokenModel</strong> is a regular model, but you will usually be interacting with it through specific methods.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Issue a token $model = new AccessTokenModel(); $accessToken = $model->issue(Gdn::session()->UserID, '1 month', $scope); // Verify a token. $tokenRow = $model->verify($accessToken); // Revoke a token. $model->revoke($accessToken); </pre><p>When a token is issued it is also signed with its expiry date and a secure hash. These are verified before a token is looked up to help prevent certain brute force attacks. Even if an access token passes its check it must also be verified from the database. In this way access tokens can be revoked before they expire.</p><h2 data-id="access-token-scope-(wip)">Access Token Scope (WIP)</h2><p>The <strong>issue()</strong> method has a scope parameter. This can be left empty or you can specify an array of permission names. If you specify a scope like this then the access token will reduce the permissions of the user for the request to those listed in the scope. In this way access tokens can be issued with less permissions than a user has. It’s considered a best practice to use a scope with only the permissions you need.</p><p><em>You can never have a scope that gives a user more permissions than they already have. If more permissions are specified, they’ll be ignored.</em></p><h2 data-id="passing-access-tokens">Passing Access Tokens</h2><p>Access tokens are past to REST requests in the <strong>Authorization</strong> header. You pass an access token with the bearer scheme:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">Authorization: Bearer <access token> </pre><p>If the access token verifies then the request will be made with the appropriate user. If it doesn’t then there will be a 401 error. In this case check the <strong>X-WWW-Authenticate</strong> header for specific information.</p> </article> </main>