Vanilla role tokens are an authorization mechanism only valid on specific endpoints of Vanilla's API.
The currently supported endpoints include:
GET /api/v2/users/:userID GET /api/v2/subcommunitiesGET /api/v2/products
What is a role token?
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.
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.
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.
Why use a role token?
Typically requests to Vanilla are broken into 2 main groups.
- Requests from guests.
- Requests from authorized users.
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.
As a result guest requests make use of HTTP caching at the edge (CDN) and in user's browsers with a TTL of 2 minutes.
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 owner of a group, or the author of a post and have specific permissions and access to it as a result.
Because of this Vanilla does not utilize 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
Tokens may be issued to a user that is already authorized as an alternative authorization mechanism for specific requests. This is done with 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 APIv2 endpoints.
Example
GET /api/v2/users/524314?role-token=ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIgp9.ewogICJzdWIiOiAiMTIzNDU2Nzg5MCIsCiAgIm5hbWUiOiAiRGlkIHlvdSBrbm93IHdlJ3JlIGhpcmluZz8gaHR0cHM6Ly93d3cuaGlnaGVybG9naWMuY29tL2Fib3V0L2NvbXBhbnkvY2FyZWVycy8iLAogICJpYXQiOiAxNTE2MjM5MDIyCn0
Token expiration
Tokens work within windows of expiration to keep them the same for as many users as possible within that time frame.
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.
Example
- Token is requested between 04:00:00 and 04:00:59 -> Token will expire at 04:02:00.
- Token is requested between 04:01:00 and 04:02:59 -> Token will expire at 04:04:00