From ec20f154073c33d22922f1cb4f33fdb0352e78df Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 19 Jul 2016 09:17:14 +0100 Subject: [PATCH] /tokenrefresh should expire the access token It's possible for clients to call /tokenrefresh before the access_token has expired, potentially leading to a proliferation of valid access_tokens. --- api/client-server/login.yaml | 10 +++++++--- changelogs/client_server.rst | 2 ++ specification/client_server_api.rst | 3 +++ 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index a9724efc..34b33cf3 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -90,9 +90,8 @@ paths: refresh for a new token on failure, and retry the request with the new token. refresh_token: type: string - # TODO: Work out how to linkify /tokenrefresh description: |- - (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. + Optional. A ``refresh_token`` may be exchanged for a new ``access_token`` using the |/tokenrefresh|_ API endpoint. home_server: type: string description: The hostname of the homeserver on which the account has been registered. @@ -123,6 +122,11 @@ paths: description: |- Exchanges a refresh token for a new access token. This is intended to be used if the access token has expired. + + The server MUST invalidate the supplied ``refresh_token`` if the + request is successful. It MUST also invalidate the ``access_token`` + which was issued at the same time as the ``refresh_token``, if it + has not already expired. security: - accessToken: [] parameters: @@ -163,7 +167,7 @@ paths: The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``. refresh_token: type: string - description: (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the TODO Linkify /tokenrefresh API endpoint. + description: Optional. A new ``refresh_token`` which may be exchanged for another new ``access_token``. 403: description: |- The exchange attempt failed. For example, the refresh token may have already been used. diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 6fcebbbf..8667d319 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -5,6 +5,8 @@ - Spell out the way that state is handled by ``POST /createRoom`` (`#362 `_). + - Emphasise that ``POST /tokenrefresh`` should expire the access token + (`#363 `_). r0.2.0 ====== diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 23cbbf3a..9a342413 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1191,6 +1191,9 @@ have to wait in milliseconds before they can try again. .. |/initialSync| replace:: ``/initialSync`` .. _/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync +.. |/tokenrefresh| replace:: ``/tokenrefresh`` +.. _/tokenrefresh: #post-matrix-client-%CLIENT_MAJOR_VERSION%-tokenrefresh + .. |/sync| replace:: ``/sync`` .. _/sync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-sync