Remove duplicated registration/login APIs

Currently the spec duplicates all of the account-management APIs. There's still
work to be done here, but the complete duplication is confusing.
pull/128/head
Richard van der Hoff 9 years ago
parent 0639f885df
commit 28ab643a4e

@ -89,6 +89,11 @@ paths:
These errors may be returned at any stage of the registration process, These errors may be returned at any stage of the registration process,
including after authentication if the requested user ID was registered including after authentication if the requested user ID was registered
whilst the client was performing authentication. whilst the client was performing authentication.
Home Servers MUST perform the relevant checks and return these codes before
performing `User-Interactive Authentication`_, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
examples: examples:
application/json: |- application/json: |-
{ {

@ -349,67 +349,21 @@ This MUST return an HTML page which can perform this authentication stage. This
page must attempt to call the JavaScript function ``window.onAuthDone`` when page must attempt to call the JavaScript function ``window.onAuthDone`` when
the authentication has been completed. the authentication has been completed.
Registration API calls using the User-Interactive Authentication mechanism
~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section refers to API Version 2. These API calls currently use the prefix This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``. ``/_matrix/client/v2_alpha``.
Registering for a user account is done using the request::
POST $V2PREFIX/register
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint does not require an access token.
.. _User-Interactive Authentication API: `sect:auth-api`_
The body of the POST request is a JSON object containing:
username
Optional. This is the local part of the desired Matrix ID. If omitted, the
Home Server must generate a Matrix ID local part.
password
Required. The desired password for the account.
bind_email
Optional. If ``true``, the server binds the email used for authentication to
the Matrix ID with the ID Server.
On success, this returns a JSON object with keys:
user_id
The fully-qualified Matrix ID that has been registered.
access_token
An access token for the new account.
home_server
The hostname of the Home Server on which the account has been registered.
refresh_token
A token that may be exchanged for a new ``access_token`` using the
``/tokenrefresh`` API endpoint.
This endpoint may also return the following error codes:
M_USER_IN_USE
If the Matrix ID is already in use
M_EXCLUSIVE
If the requested Matrix ID is in the exclusive namespace of an application
service.
Home Servers MUST perform the relevant checks and return these codes before
performing `User-Interactive Authentication`_, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
.. _User-Interactive Authentication: `sect:auth-api`_ .. _User-Interactive Authentication: `sect:auth-api`_
{{v2_registration_http_api}}
Old V1 API docs: |register|_ Old V1 API docs: |register|_
{{login_http_api}} {{login_http_api}}
Changing Password Changing Password
+++++++++++++++++ +++++++++++++++++
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request:: Request::
POST $V2PREFIX/account/password POST $V2PREFIX/account/password
@ -432,9 +386,6 @@ database.
Adding Account Administrative Contact Information Adding Account Administrative Contact Information
+++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request:: Request::
POST $V2PREFIX/account/3pid POST $V2PREFIX/account/3pid
@ -470,9 +421,6 @@ M_THREEPID_AUTH_FAILED
Fetching Currently Associated Contact Information Fetching Currently Associated Contact Information
+++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request:: Request::
GET $V2PREFIX/account/3pid GET $V2PREFIX/account/3pid
@ -982,107 +930,6 @@ member's state, by making a request to
"membership": "ban" "membership": "ban"
} }
Account operations
------------------
Registration
~~~~~~~~~~~~
This API endpoint uses the `User-Interactive Authentication API`_.
{{v2_registration_http_api}}
Login
~~~~~
{{login_http_api}}
Changing Password
~~~~~~~~~~~~~~~~~
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request::
POST $V2PREFIX/account/password
This API endpoint uses the User-Interactive Authentication API. An access token
should be submitted to this endpoint if the client has an active session. The
Home Server may change the flows available depending on whether a valid access
token is provided.
The body of the POST request is a JSON object containing:
new_password
The new password for the account.
On success, an empty JSON object is returned.
The error code M_NOT_FOUND is returned if the user authenticated with a third
party identifier but the Home Server could not find a matching account in its
database.
Adding a Third Party Identifier
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request::
POST $V2PREFIX/account/3pid
Used to add a third party identifier to the user's account.
The body of the POST request is a JSON object containing:
threePidCreds
An object containing third party identifier credentials.
bind
Optional. A boolean indicating whether the Home Server should also bind this
third party identifier to the account's matrix ID with the Identity Server. If
supplied and true, the Home Server must bind the 3pid accordingly.
The third party identifier credentials object comprises:
id_server
The colon-separated hostname and port of the Identity Server used to
authenticate the third party identifier. If the port is the default, it and the
colon should be omitted.
sid
The session ID given by the Identity Server
client_secret
The client secret used in the session with the Identity Server.
On success, the empty JSON object is returned.
May also return error codes:
M_THREEPID_AUTH_FAILED
If the credentials provided could not be verified with the ID Server.
Fetching Currently Associated Third Party Identifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Request::
GET $V2PREFIX/account/3pid
This returns a list of third party identifiers that the Home Server has
associated with the user's account. This is *not* the same as the list of third
party identifiers bound to the user's Matrix ID in Identity Servers. Identifiers
in this list may be used by the Home Server as, for example, identifiers that it
will accept to reset the user's account password.
Returns a JSON object with the key ``threepids`` whose contents is an array of
objects with the following keys:
medium
The medium of the 3pid (eg, ``email``)
address
The textual address of the 3pid, eg. the email address
Profiles Profiles
-------- --------

Loading…
Cancel
Save