diff --git a/api/client-server/v2_alpha/registration.yaml b/api/client-server/v2_alpha/registration.yaml index 5222b3f3..a53d4f41 100644 --- a/api/client-server/v2_alpha/registration.yaml +++ b/api/client-server/v2_alpha/registration.yaml @@ -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: |- { diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 791c1f4a..89b6666a 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -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 --------