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.
This commit is contained in:
Richard van der Hoff
parent
0639f885df
commit
28ab643a4e
2 changed files with 9 additions and 157 deletions
|
|
@ -89,6 +89,11 @@ paths:
|
|||
These errors may be returned at any stage of the registration process,
|
||||
including after authentication if the requested user ID was registered
|
||||
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:
|
||||
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
|
||||
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
|
||||
``/_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`_
|
||||
|
||||
{{v2_registration_http_api}}
|
||||
|
||||
Old V1 API docs: |register|_
|
||||
|
||||
{{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
|
||||
|
|
@ -432,9 +386,6 @@ database.
|
|||
|
||||
Adding Account Administrative Contact Information
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
This section refers to API Version 2. These API calls currently use the prefix
|
||||
``/_matrix/client/v2_alpha``.
|
||||
|
||||
Request::
|
||||
|
||||
POST $V2PREFIX/account/3pid
|
||||
|
|
@ -470,9 +421,6 @@ M_THREEPID_AUTH_FAILED
|
|||
|
||||
Fetching Currently Associated Contact Information
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
This section refers to API Version 2. These API calls currently use the prefix
|
||||
``/_matrix/client/v2_alpha``.
|
||||
|
||||
Request::
|
||||
|
||||
GET $V2PREFIX/account/3pid
|
||||
|
|
@ -982,107 +930,6 @@ member's state, by making a request to
|
|||
"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
|
||||
--------
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue