In Higher Logic Vanilla (Vanilla), Role tokens are an authorization mechanism that are valid on only the following endpoints of Vanilla's API.
GET /api/v2/users/:userID GET /api/v2/subcommunitiesGET /api/v2/products
What is a Role token?
A Role token is a signed JSON Web Token (JWT) with claims about a set of Roles. These tokens are valid for one to three minutes, depending on when they are issued. Expiration of tokens occurs every two minutes.
The goal of a Role token is to have an authorization mechanism for specific resources that are the same for all users who have the same permissions. Thousands of users who make requests may share the same Roles and be able to make use of HTTP-caching for the same result. This significantly speeds up requests.
Role tokens contain claims about Roles only (and therefore, permissions) — but not claims about a userID or sessionID — so, they cannot be used anywhere that requires a user identity.
Why use a Role token?
Typically, requests to Vanilla fall into one of two groups:
- Requests from guests
- Requests from authorized users
Guests
Requests from guests are the same for all guests, and it's easy for Vanilla to distinguish between the two. Additionally, there is no difference between the contents that two guests will see. Guests always have the same permissions and no user identity to affect the actions they can take.
- As a result, guest requests use HTTP-caching at the edge (CDN) and in user's browsers with a TTL of two minutes.
Authorized users
Authorized users can have a combination of Roles. Therefore, two authorized users, who have the same Roles, could have differing access to resources, based on user identity. For example, an authorized user may be the owner of a group or the author of a post and, as a result, be able to access that group or post, while a different authorized user, with an identical combination of Roles, may not.
- Because of this, Vanilla does not use HTTP-caching for authorized users.
Role token caching
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.
How to get and use a Role token
Role tokens may be issued to a user who is already authorized as an alternative-authorization mechanism for specific requests. This is done with the POST /api/v2/tokens/roles endpoint, which will return the token and the expiration of it.
- 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.
- Tokens are used by passing them as a
role-token query parameter to various API v2 endpoints.
Example
GET /api/v2/users/524314?role-token=ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIgp9.ewogICJzdWIiOiAiMTIzNDU2Nzg5MCIsCiAgIm5hbWUiOiAiRGlkIHlvdSBrbm93IHdlJ3JlIGhpcmluZz8gaHR0cHM6Ly93d3cuaGlnaGVybG9naWMuY29tL2Fib3V0L2NvbXBhbnkvY2FyZWVycy8iLAogICJpYXQiOiAxNTE2MjM5MDIyCn0
Role token expiration
Role tokens work within a time-based expiration window in order to keep them the same for as many users as possible within that window.
Currently, they work on a two-minute window with a one-minute rollover time. This means that a token should be valid for between one and three minutes.
Examples
- A Role token that is requested between 04:00:00 and 04:00:59 will expire at 04:02:00.
- A Role token that is requested between 04:01:00 and 04:02:59 will expire at 04:04:00.