Authenticating APIv2 calls with Role-Based Tokens - Vanilla Success
<main> <article class="userContent"> <p>Vanilla role tokens 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 JWT with claims about a set of roles. These tokens are valid for 1-3 minutes depending on when they are issued. Expiration of tokens occurs every 2 minutes.</p><p>The goal of a role token is to have an authorization mechanism for specific resources that 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 2 main groups.</p><ul><li>Requests from guests.</li><li>Requests from authorized users.</li></ul><p>Requests from guests are the same for all guests and it is very easy for Vanilla to distinguish between the two. Additionally there is no difference between the contents that 2 guests will ever see. Guests always have the same permissions and no user identity to affect the actions they can take. </p><p>As a result <strong>guest requests make use of HTTP caching at the edge (CDN) and in user's browsers with a TTL of 2 minutes.</strong></p><p>Authorized users could have any combination of roles and, even when 2 user's 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><p>Because of this Vanilla <strong>does not utilize HTTP caching for authorized users</strong>.</p><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 that is already authorized as an alternative authorization mechanism for specific requests. This is done with <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><p>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.</p><p>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.</p><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 2 minute window with a 1 minute rollover time. This means a token should be valid for between 1 and 3 minutes.</p><p><strong>Example</strong></p><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>