wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1517 from turt2live/travis/c2s/auth-header

Browse source 
Dedicate a section on how to use access tokens
This commit is contained in:
Travis Ralston 2018-08-20 10:08:18 -06:00 • committed by GitHub
commit 26746cf785
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 19 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1517.clarification Normal file
View file

@ -0,0 +1 @@
Clarify how access tokens are meant to be supplied to the homeserver.

22
specification/client_server_api.rst
View file

@ -191,10 +191,6 @@ previously obtained credentials in the form of an ``access_token`` query
parameter or through an Authorization Header of ``Bearer $access_token``.
An access token is typically obtained via the `Login`_ or `Registration`_ processes.
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
``M_UNKNOWN_TOKEN`` respectively.
.. NOTE::
This specification does not mandate a particular format for the access
@ -202,6 +198,24 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
to choose an appropriate format. Server implementors may like to investigate
`macaroons <macaroon_>`_.
Using access tokens
~~~~~~~~~~~~~~~~~~~
Access tokens may be provided in two ways, both of which the homeserver MUST
support:
1. Via a query string parameter, ``access_token=TheTokenHere``.
#. Via a request header, ``Authorization: Bearer TheTokenHere``.
Clients are encouraged to use the ``Authorization`` header where possible
to prevent the access token being leaked in access/HTTP logs. The query
string should only be used in cases where the ``Authorization`` header is
inaccessible for the client.
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
``M_UNKNOWN_TOKEN`` respectively.
Relationship between access tokens and devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~