In Higher Logic Vanilla (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 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 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 two main 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 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 two minutes.
Authorized users
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 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 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
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 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 two-minute window with a one-minute rollover time. This means a token should be valid between one and three 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