Support for refresh tokens

Sometimes Matrix servers will issue access_tokens that expire. In that case, they also issue a refresh_token that allows the client to obtain a new access_token.

Matrix spec: https://spec.matrix.org/v1.6/client-server-api/#refreshing-access-tokens

Uhoreg also has a nice section in his tutorial: https://uhoreg.gitlab.io/matrix-tutorial/authentication.html

Application: Circles Subscriptions

Update: The plan for Circles subscriptions is to break with the official Matrix spec and require UIA on the /refresh endpoint. While the user's subscription is valid, the UIA will be satisfied on the server side with no visible difference to the client. But once the subscription expires, then calling POST /refresh will result in a HTTP 401 UIA response.

Refresh Tokens: How do they work?

1. When we call POST /login or POST /register, we set refresh_token: true in the request body to tell the server that we support using refresh tokens.
   • Once we require subscriptions, our server will reject any client who doesn't set refresh_token to true.
2. The server returns the access_token and the rest of the credentials as usual, plus also
   • The lifetime (in milliseconds) expires_in_ms that our access token is valid, eg. expires_in_ms: 86400000 for 24 hours
   • A refresh token eg. refresh_token: "abcd1234" that we can use to refresh and get a new access token
3. We can call POST /refresh at any time to obtain a new access token and a new refresh token
   • On iOS, I will probably have a background task that attempts to refresh the token before it expires.
4. If we don't refresh our token before it expires, then the next time we hit an endpoint, we will receive an HTTP 403 response with error M_UNKNOWN_TOKEN. When this happens, we need to call POST /refresh to get a new access token, and then we can re-try the original call with our new access token.
   • Even if we do try to refresh our tokens before they expire, we still should expect for this case to be common. For example, maybe the device has been powered off, or the app has been closed, so we were unable to call POST /refresh.