Remove references to refresh tokens and tokenrefresh

refresh tokens are dead.
pull/977/head
Richard van der Hoff 8 years ago
parent 1f45724bfd
commit f4c7fdfd03

@ -13,6 +13,6 @@
# limitations under the License. # limitations under the License.
accessToken: accessToken:
type: apiKey type: apiKey
description: The access_token returned by a call to ``/login`` or ``/tokenrefresh`` description: The access_token returned by a call to ``/login`` or ``/register``
name: access_token name: access_token
in: query in: query

@ -90,15 +90,6 @@ paths:
description: |- description: |-
An access token for the account. An access token for the account.
This access token can then be used to authorize other requests. This access token can then be used to authorize other requests.
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
There is no specific error message to indicate that a request has failed because
an access token has expired; instead, if a client has reason to believe its
access token is valid, and it receives an auth error, they should attempt to
refresh for a new token on failure, and retry the request with the new token.
refresh_token:
type: string
description: |-
Optional. A ``refresh_token`` may be exchanged for a new ``access_token`` using the |/tokenrefresh|_ API endpoint.
home_server: home_server:
type: string type: string
description: The hostname of the homeserver on which the account has been registered. description: The hostname of the homeserver on which the account has been registered.
@ -123,67 +114,3 @@ paths:
"$ref": "definitions/error.yaml" "$ref": "definitions/error.yaml"
tags: tags:
- Session management - Session management
"/tokenrefresh":
post:
summary: Exchanges a refresh token for an access token.
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:
- in: body
name: body
schema:
type: object
example: |-
{
"refresh_token": "a1b2c3"
}
properties:
refresh_token:
type: string
description: The refresh token which was issued by the server.
required: ["refresh_token"]
responses:
200:
description: |-
The refresh token was accepted, and a new access token has been issued.
The passed refresh token is no longer valid and cannot be used.
A new refresh token will have been returned unless some policy does
not allow the user to continue to renew their session.
examples:
application/json: |-
{
"access_token": "bearwithme123",
"refresh_token": "exchangewithme987"
}
schema:
type: object
properties:
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
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 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.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN"}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management

@ -39,6 +39,9 @@ paths:
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
If registration is successful, this endpoint will issue an access token
the client can use to authorize itself in subsequent requests.
parameters: parameters:
- in: query - in: query
name: kind name: kind
@ -90,8 +93,7 @@ paths:
{ {
"user_id": "@cheeky_monkey:matrix.org", "user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123", "access_token": "abc123",
"home_server": "matrix.org", "home_server": "matrix.org"
"refresh_token": "def456"
} }
schema: schema:
type: object type: object
@ -104,16 +106,6 @@ paths:
description: |- description: |-
An access token for the account. An access token for the account.
This access token can then be used to authorize other requests. This access token can then be used to authorize other requests.
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
There is no specific error message to indicate that a request has failed because
an access token has expired; instead, if a client has reason to believe its
access token is valid, and it receives an auth error, they should attempt to
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.
home_server: home_server:
type: string type: string
description: The hostname of the homeserver on which the account has been registered. description: The hostname of the homeserver on which the account has been registered.

@ -8,23 +8,11 @@
which support push rules, but any other clients implementing which support push rules, but any other clients implementing
the push rules API should be aware of this change. This the push rules API should be aware of this change. This
makes it simple to mute rooms correctly in the API. makes it simple to mute rooms correctly in the API.
(`#373 <https://github.com/matrix-org/matrix-doc/pull/373>`_).
- Spec clarifications: - Remove ``/tokenrefresh`` from the API.
(`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
- Spell out the way that state is handled by ``POST /createRoom`` - Remove requirement that tokens used in token-based login be macaroons.
(`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_). (`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
- Emphasise that ``POST /tokenrefresh`` should expire the access token
(`#363 <https://github.com/matrix-org/matrix-doc/pull/363>`_).
- Clarify the fields which are applicable to different types of push rule
(`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
- A number of clarifications to authentication
(`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
- Correct references to ``user_id`` which should have been ``sender``
(`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
- Correct inconsistent specification of ``redacted_because`` fields and their
values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
- Mark required fields in response objects as such
(`#394 <https://github.com/matrix-org/matrix-doc/pull/394>`_).
- Changes to the API which will be backwards-compatible for clients: - Changes to the API which will be backwards-compatible for clients:
@ -42,6 +30,21 @@
- Add ``filter`` optional query param to ``/messages`` - Add ``filter`` optional query param to ``/messages``
(`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_). (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
- Spec clarifications:
- Spell out the way that state is handled by ``POST /createRoom``
(`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
- Clarify the fields which are applicable to different types of push rule
(`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
- A number of clarifications to authentication
(`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
- Correct references to ``user_id`` which should have been ``sender``
(`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
- Correct inconsistent specification of ``redacted_because`` fields and their
values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
- Mark required fields in response objects as such
(`#394 <https://github.com/matrix-org/matrix-doc/pull/394>`_).
r0.2.0 r0.2.0
====== ======

@ -158,14 +158,23 @@ recommended.
Client Authentication Client Authentication
--------------------- ---------------------
Most API endpoints require the user to identify themselves by presenting Most API endpoints require the user to identify themselves by presenting
previously obtained credentials in the form of an ``access_token`` query previously obtained credentials in the form of an ``access_token`` query
parameter. parameter. An access token is typically obtained via the `Login`_ or
`Registration`_ processes.
When credentials are required but missing or invalid, the HTTP call will When credentials are required but missing or invalid, the HTTP call will
return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
``M_UNKNOWN_TOKEN`` respectively. ``M_UNKNOWN_TOKEN`` respectively.
.. NOTE::
This specification does not mandate a particular format for the access
token. Clients should treat it as an opaque byte sequence. Servers are free
to choose an appropriate format. Server implementors may like to investigate
`macaroons <macaroon_>`_.
User-Interactive Authentication API User-Interactive Authentication API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -460,8 +469,8 @@ server side, as well as potentially invalidating the token completely once the
device has successfully logged in (e.g. when we receive a request from the device has successfully logged in (e.g. when we receive a request from the
newly provisioned access_token). newly provisioned access_token).
The ``token`` must be a macaroon, with a caveat encoding the user id. There is The server must encode the user id in the ``token``. There is therefore no need
therefore no need for the client to submit a separate username. for the client to submit a separate username.
OAuth2-based OAuth2-based
<<<<<<<<<<<< <<<<<<<<<<<<
@ -595,9 +604,9 @@ follows:
"token": "<login token>" "token": "<login token>"
} }
As with `token-based`_ interactive login, the ``token`` must be a macroon with As with `token-based`_ interactive login, the ``token`` must encode the
a caveat which includes the user id. In the case that the token is not valid, the user id. In the case that the token is not valid, the homeserver must respond
homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``. with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``.
{{login_cs_http_api}} {{login_cs_http_api}}
@ -615,6 +624,8 @@ This returns an HTML and JavaScript page which can perform the entire login
process. The page will attempt to call the JavaScript function process. The page will attempt to call the JavaScript function
``window.onLogin`` when login has been successfully completed. ``window.onLogin`` when login has been successfully completed.
.. _Registration:
Account registration and management Account registration and management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1230,6 +1241,9 @@ have to wait in milliseconds before they can try again.
homeserver come up with their own idea, causing totally unpredictable performance over homeserver come up with their own idea, causing totally unpredictable performance over
federated rooms? federated rooms?
.. References
.. _`macaroon`: http://research.google.com/pubs/pub41892.html
.. Links through the external API docs are below .. Links through the external API docs are below
.. ============================================= .. =============================================
@ -1237,9 +1251,6 @@ have to wait in milliseconds before they can try again.
.. |/initialSync| replace:: ``/initialSync`` .. |/initialSync| replace:: ``/initialSync``
.. _/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync .. _/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync
.. |/tokenrefresh| replace:: ``/tokenrefresh``
.. _/tokenrefresh: #post-matrix-client-%CLIENT_MAJOR_VERSION%-tokenrefresh
.. |/sync| replace:: ``/sync`` .. |/sync| replace:: ``/sync``
.. _/sync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-sync .. _/sync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-sync

Loading…
Cancel
Save