diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 41270535..504e149d 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -1,4 +1,5 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -89,8 +90,19 @@ paths: - User data post: summary: Adds contact information to the user's account. - description: Adds contact information to the user's account. + description: |- + Adds contact information to the user's account. + + This endpoint is deprecated in favour of the more specific ``/3pid/add`` + and ``/3pid/bind`` endpoints. + + .. Note:: + Previously this endpoint supported a ``bind`` parameter. This parameter + has been removed, making this endpoint behave as though it was ``false``. + This results in this endpoint being an equivalent to ``/3pid/bind`` rather + than dual-purpose. operationId: post3PIDs + deprecated: true security: - accessToken: [] parameters: @@ -120,13 +132,6 @@ paths: type: string description: The session identifier given by the identity server. required: ["client_secret", "id_server", "id_access_token", "sid"] - bind: - type: boolean - description: |- - Whether the homeserver should also bind this third party - identifier to the account's Matrix ID with the passed identity - server. Default: ``false``. - x-example: true required: ["three_pid_creds"] example: { "three_pid_creds": { @@ -134,8 +139,7 @@ paths: "id_access_token": "abc123_OpaqueString", "sid": "abc123987", "client_secret": "d0n'tT3ll" - }, - "bind": false + } } responses: 200: @@ -173,6 +177,113 @@ paths: "$ref": "definitions/errors/error.yaml" tags: - User data + "/account/3pid/add": + post: + summary: Adds contact information to the user's account. + description: |- + This API endpoint uses the `User-Interactive Authentication API`_. + + Adds contact information to the user's account. Homeservers should use 3PIDs added + through this endpoint for password resets instead of relying on the identity server. + + Homeservers should prevent the caller from adding a 3PID to their account if it has + already been added to another user's account on the homeserver. + operationId: add3PID + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + $ref: "definitions/auth_data.yaml" + client_secret: + type: string + description: The client secret used in the session with the homeserver. + sid: + type: string + description: The session identifier given by the homeserver. + required: ["client_secret", "sid"] + example: { + "sid": "abc123987", + "client_secret": "d0n'tT3ll" + } + responses: + 200: + description: The addition was successful. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + "/account/3pid/bind": + post: + summary: Binds a 3PID to the user's account through an Identity Service. + description: |- + Binds a 3PID to the user's account through the specified identity server. + + Homeservers should not prevent this request from succeeding if another user + has bound the 3PID. Homeservers should simply proxy any errors received by + the identity server to the caller. + + Homeservers should track successful binds so they can be unbound later. + operationId: bind3PID + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + sid: + type: string + description: The session identifier given by the identity server. + required: ["client_secret", "id_server", "id_access_token", "sid"] + example: { + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "d0n'tT3ll" + } + responses: + 200: + description: The addition was successful. + examples: + application/json: {} + schema: + type: object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data "/account/3pid/delete": post: summary: Deletes a third party identifier from the user's account @@ -308,12 +419,9 @@ paths: already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of - the |/register/email/requestToken|_ endpoint. The homeserver has the - choice of validating the email address itself, or proxying the request - to the ``/validate/email/requestToken`` Identity Service API as - identified by ``id_server``. It is imperative that the - homeserver keep a list of trusted Identity Servers and only proxies to - those that it trusts. + the |/register/email/requestToken|_ endpoint. The homeserver should validate + the email itself, either by sending a validation email itself or by using + a service it has control over. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -361,12 +469,9 @@ paths: already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of - the |/register/msisdn/requestToken|_ endpoint. The homeserver has the - choice of validating the phone number itself, or proxying the request - to the ``/validate/msisdn/requestToken`` Identity Service API as - identified by ``id_server``. It is imperative that the - homeserver keep a list of trusted Identity Servers and only proxies to - those that it trusts. + the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate + the phone number itself, either by sending a validation message itself or by using + a service it has control over. operationId: requestTokenTo3PIDMSISDN parameters: - in: body diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a4c5bf71..8114299e 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -219,11 +219,8 @@ paths: description: |- The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver - has the choice of validating the email address itself, or proxying the - request to the ``/validate/email/requestToken`` Identity Service API. The - request should be proxied to the domain that is sent by the client in - the ``id_server``. It is imperative that the homeserver keep a list of - trusted Identity Servers and only proxies to those it trusts. + should validate the email itself, either by sending a validation email + itself or by using a service it has control over. operationId: requestTokenToRegisterEmail parameters: - in: body @@ -272,11 +269,8 @@ paths: description: |- The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver - has the choice of validating the phone number itself, or proxying the - request to the ``/validate/msisdn/requestToken`` Identity Service API. The - request should be proxied to the domain that is sent by the client in - the ``id_server``. It is imperative that the homeserver keep a list of - trusted Identity Servers and only proxies to those it trusts. + should validate the phone number itself, either by sending a validation + message itself or by using a service it has control over. operationId: requestTokenToRegisterMSISDN parameters: - in: body @@ -388,12 +382,8 @@ paths: email to the given address prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the email address itself, - or proxying the request to the ``/validate/email/requestToken`` - Identity Service API. The request should be proxied to the domain that - is sent by the client in the ``id_server``. It is imperative that the - homeserver keep a list of trusted Identity Servers and only proxies to - those that it trusts. + The homeserver should validate the email itself, either by sending a + validation email itself or by using a service it has control over. .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -451,12 +441,8 @@ paths: to the given phone number prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the phone number itself, or - proxying the request to the ``/validate/msisdn/requestToken`` Identity - Service API. The request should be proxied to the domain that is sent - by the client in the ``id_server``. It is imperative that the - homeserver keep a list of trusted Identity Servers and only proxies to - those that it trusts. + The homeserver should validate the phone number itself, either by sending a + validation message itself or by using a service it has control over. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 81fb28a6..d1d5dee4 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1138,7 +1138,15 @@ Adding Account Administrative Contact Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A homeserver may keep some contact information for administrative use. -This is independent of any information kept by any identity servers. +This is independent of any information kept by any identity servers, though +can be proxied (bound) to the identity server in many cases. + +.. Note:: + This section deals with two terms: "add" and "bind". Where "add" (or "remove") + is used, it is speaking about an identifier that was not bound to an identity + server. As a result, "bind" (or "unbind") references an identifier that is found + in an identity server. Note that an identifer can be added and bound at the same + time, depending on context. {{administrative_contact_cs_http_api}}