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

Encourage appservices to use the Authorization header

Browse source 
This also throws in a mention about how to handle a request with a lack of user_id.

The request samples now encourage the use of the header over the query string, and have had their sample values added for some readability. 

Fixes https://github.com/matrix-org/matrix-doc/issues/1296
Fixes https://github.com/matrix-org/matrix-doc/issues/1424
This commit is contained in:
Travis Ralston 2018-08-17 13:49:24 -06:00
parent f5dc0eaed2
commit 857bcc0fe7
1 changed files with 21 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

36
specification/application_service_api.rst
View file

@ -192,22 +192,28 @@ they wish to be acting on behalf of. For real users, this would require
additional permissions granting the AS permission to masquerade as a matrix user.
Inputs:
- Application service token (``access_token``)
- Application service token (``as_token``)
- User ID in the AS namespace to act as.
Notes:
- This will apply on all aspects of the CS API, except for Account Management.
- This will apply on all aspects of the Client-Server API, except for Account Management.
- The ``as_token`` is inserted into ``access_token`` which is usually where the
client token is. This is done on purpose to allow application services to
reuse client SDKs.
client token is, such as via the query string or ``Authorization`` header. This
is done on purpose to allow application services to reuse client SDKs.
- The ``access_token`` should be supplied through the ``Authorization`` header where
possible to prevent the token appearing in HTTP request logs by accident.
::
The application service may specify the virtual user to act as through use of a
``user_id`` query string parameter on the request. The user specified in the query
string must be covered by one of the application service's ``user`` namespaces. If
the parameter is missing, the homeserver is to assume the application service intends
to act as the user implied by the ``sender_localpart`` property of the registration.
/path?access_token=$token&user_id=$userid
An example request would be::
GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org
Authorization: Bearer YourApplicationServiceTokenHere
Query Parameters:
access_token: The application service token
user_id: The desired user ID to act as.
Timestamp massaging
+++++++++++++++++++
@ -223,11 +229,10 @@ Notes:
::
/path?access_token=$token&ts=$timestamp
PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283
Authorization: Bearer YourApplicationServiceTokenHere
Query Parameters added to the send event APIs only:
access_token: The application service token
ts: The desired timestamp
Content: The event to send, as per the Client-Server API.
Server admin style permissions
++++++++++++++++++++++++++++++
@ -250,12 +255,13 @@ including the AS token on a ``/register`` request, along with a login type of
::
/register?access_token=$as_token
POST /_matrix/client/%CLIENT_MAJOR_VERSION%/register
Authorization: Bearer YourApplicationServiceTokenHere
Content:
{
type: "m.login.application_service",
username: "<desired user localpart in AS namespace>"
username: "_irc_example"
}
Application services which attempt to create users or aliases *outside* of