Authenticating APIv2 calls with Role-Based Tokens - HL Vanilla Community
<main> <article class="userContent"> <p>In <strong>Higher Logic Vanilla (Vanilla)</strong>, <strong>role tokens </strong>are an authorization mechanism only valid on specific endpoints of Vanilla's API.</p><p>The currently supported endpoints include:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/users/:userID</code> </li><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/subcommunities</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/products</code> </li></ul><h2 data-id="what-is-a-role-token">What is a role token?</h2><p>A role token is a signed <strong>JSON Web Token (JWT)</strong> with claims about a set of roles. These tokens are <strong>valid </strong>for <strong>one </strong>to <strong>three minutes</strong>, depending on when they are issued. <strong>Expiration </strong>of tokens occurs every <strong>two minutes</strong>.</p><p>The goal of a role token is to have an authorization mechanism for specific resources that are the same for all users that share the same permissions. Thousands of user's making requests may share the same roles and be able to make use of HTTP-caching for the same result. This speeds up requests significantly.</p><p>Because tokens only contain claims about roles (and therefor permissions), but no claims about a userID or sessionID, they cannot be used anywhere that requires a user identity. </p><h2 data-id="why-use-a-role-token">Why use a role token?</h2><p>Typically, requests to Vanilla are broken into two main groups:</p><ul><li>Requests from guests</li><li>Requests from authorized users</li></ul><h3 data-id="guests">Guests</h3><p>Requests from guests are the same for <em>all</em> guests, and it's easy for Vanilla to distinguish between the two. Additionally, there is no difference between the contents that two guests will ever see. Guests always have the same permissions and no user identity to affect the actions they can take. </p><ul><li>As a result, <strong>guest requests make use of HTTP-caching at the edge (CDN) and in user's browsers with a TTL of two minutes.</strong></li></ul><h3 data-id="authorized-users">Authorized users</h3><p>Authorized users could have any combination of roles and, even when two users have the same roles, resources could differ based on the user's identity. For example, a user may be the <strong><em>owner</em></strong> of a group or the <strong><em>author </em></strong>of a post and have specific permissions and access to it as a result.</p><ul><li>Because of this, Vanilla <strong>does not use HTTP-caching for authorized users</strong>.</li></ul><h3 data-id="role-token-caching">Role token caching</h3><p>Role tokens are able to get similar benefits to a guest request because they create groups of users that response caches can be shared between.</p><h2 data-id="how-to-get-and-use-a-role-token">How to get and use a role token</h2><p>Tokens may be issued to a user who is already authorized as an alternative-authorization mechanism for specific requests. This is done with the <code class="code codeInline" spellcheck="false" tabindex="0">POST /api/v2/tokens/roles</code> endpoint, which will return the token and the expiration of it.</p><ul><li>Additionally, the token is a signed (but not opaque) JWT, so the expiration may be checked at any point in the future by inspecting the JWT.</li><li>Tokens are used by passing them as a <code class="code codeInline" spellcheck="false" tabindex="0">role-token</code> query parameter to various APIv2 endpoints.</li></ul><p><strong>Example</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">GET /api/v2/users/524314?role-token=ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIgp9.ewogICJzdWIiOiAiMTIzNDU2Nzg5MCIsCiAgIm5hbWUiOiAiRGlkIHlvdSBrbm93IHdlJ3JlIGhpcmluZz8gaHR0cHM6Ly93d3cuaGlnaGVybG9naWMuY29tL2Fib3V0L2NvbXBhbnkvY2FyZWVycy8iLAogICJpYXQiOiAxNTE2MjM5MDIyCn0 </pre><h2 data-id="token-expiration">Token expiration</h2><p>Tokens work within windows of expiration to keep them the same for as many users as possible within that time frame.</p><p>Currently, they work on a <strong>two-minute window</strong> with a <strong>one-minute rollover time</strong>. This means a token should be valid between one and three minutes.</p><h4 data-id="example"><strong>Example</strong></h4><ul><li>Token is requested between <strong>04:00:00 </strong>and <strong>04:00:59</strong> > Token will expire at <strong>04:02:00</strong></li><li>Token is requested between <strong>04:01:00</strong> and <strong>04:02:59</strong> > Token will expire at <strong>04:04:00</strong></li></ul> </article> </main>