Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-29 23:44:10 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Address review comments

Browse source
This commit is contained in:
Andrew Morgan 2019-06-08 18:52:38 +01:00
parent a8edb066aa
commit 1776ba28d3
2 changed files with 63 additions and 101 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
api/client-server/administrative_contact.yaml
View file

@ -134,15 +134,6 @@ paths:
200: 200:
description: |- description: |-
The addition was successful. The addition was successful.
``submit_url`` is an optional field containing a URL where the
client must submit a validation token to, with identical parameters
to the Identity Service API's ``/validate/email/submitToken``
endpoint. The homeserver will send this token to the user, which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
examples: examples:
application/json: { application/json: {
"submit_url": "https://example.org/path/to/submitToken" "submit_url": "https://example.org/path/to/submitToken"
@ -153,8 +144,15 @@ paths:
submit_url: submit_url:
type: string type: string
description: |- description: |-
An optional URL to submit information to to verify a An optional field containing a URL where the client must
third-party identifier. submit the validation token to, with identical parameters
to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver
must send this token to the user (if applicable), which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
example: "https://example.org/path/to/submitToken" example: "https://example.org/path/to/submitToken"
403: 403:
description: The credentials could not be verified with the identity server. description: The credentials could not be verified with the identity server.
@ -231,14 +229,14 @@ paths:
post: post:
summary: Begins the validation process for an email address for association with the user's account. summary: Begins the validation process for an email address for association with the user's account.
description: |- description: |-
The homeserver should check that the given email address is **not** The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should already associated with an account on this homeserver. This API should
be used to request validation tokens when adding an email address to an 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 account. This API's parameters and response are identical to that of
the |/register/email/requestToken|_ endpoint. The homeserver has the the |/register/email/requestToken|_ endpoint. The homeserver has the
choice of validating the email address itself, or proxying the request choice of validating the email address itself, or proxying the request
to the ``validate/email/requestToken`` Identity Server API on the to the ``validate/email/requestToken`` Identity Service API as
server sent in ``id_server``. identified by ``id_server``.
operationId: requestTokenTo3PIDEmail operationId: requestTokenTo3PIDEmail
parameters: parameters:
- in: body - in: body
@ -262,15 +260,6 @@ paths:
An email was sent to the given address. An email was sent to the given address.
Note that this may be an email containing the validation token or Note that this may be an email containing the validation token or
it may be informing the user of an error. it may be informing the user of an error.
``submit_url`` is an optional field containing a URL where the
client must submit a validation token to, with identical parameters
to the Identity Service API's ``/validate/email/submitToken``
endpoint. The homeserver will send this token to the user, which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
schema: schema:
type: object type: object
allOf: allOf:
@ -280,11 +269,11 @@ paths:
submit_url: submit_url:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client An optional field containing a URL where the client must
must submit a validation token to, with identical submit the validation token to, with identical parameters
parameters to the Identity Service API's to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver ``/validate/email/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user, which should then be
prompted to provide it to the client. prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
@ -317,14 +306,14 @@ paths:
post: post:
summary: Begins the validation process for a phone number for association with the user's account. summary: Begins the validation process for a phone number for association with the user's account.
description: |- description: |-
The homeserver should check that the given phone number is **not** The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should already associated with an account on this homeserver. This API should
be used to request validation tokens when adding a phone number to an 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 account. This API's parameters and response are identical to that of
the |/register/msisdn/requestToken|_ endpoint. The homeserver has the the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
choice of validating the phone number itself, or proxying the request choice of validating the phone number itself, or proxying the request
to the ``validate/msisdn/requestToken`` Identity Server API on the to the ``validate/msisdn/requestToken`` Identity Service API as
server sent in ``id_server``. identified by ``id_server``.
operationId: requestTokenTo3PIDMSISDN operationId: requestTokenTo3PIDMSISDN
parameters: parameters:
- in: body - in: body
@ -345,16 +334,7 @@ paths:
responses: responses:
200: 200:
description: |- description: |-
An SMS message was sent to the given phone number. A SMS message was sent to the given phone number.
``submit_url`` is an optional field containing a URL where the
client must submit a validation token to, with identical parameters
to the Identity Service API's ``/validate/msisdn/submitToken``
endpoint. The homeserver will send this token to the user, which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
schema: schema:
type: object type: object
allOf: allOf:
@ -364,12 +344,12 @@ paths:
submit_url: submit_url:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client An optional field containing a URL where the client must
must submit a validation token to, with identical submit the validation token to, with identical parameters
parameters to the Identity Service API's to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver ``/validate/email/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user (if applicable), which
prompted to provide it to the client. should then be prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
verification will happen without the client's verification will happen without the client's

94
api/client-server/registration.yaml
View file

@ -210,10 +210,10 @@ paths:
post: post:
summary: Begins the validation process for an email to be used during registration. summary: Begins the validation process for an email to be used during registration.
description: |- description: |-
The homeserver should check that the given email address is **not** The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver already associated with an account on this homeserver. The homeserver
has the choice of validating the email address itself, or proxying the has the choice of validating the email address itself, or proxying the
request to the ``validate/email/requestToken`` Identity Server API. 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 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 the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts. trusted Identity Servers and only proxies to those it trusts.
@ -240,15 +240,6 @@ paths:
An email has been sent to the specified address. An email has been sent to the specified address.
Note that this may be an email containing the validation token or it may be informing Note that this may be an email containing the validation token or it may be informing
the user of an error. the user of an error.
``submit_url`` is an optional field containing a URL where the
client must submit a validation token to, with identical parameters
to the Identity Service API's ``/validate/email/submitToken``
endpoint. The homeserver will send this token to the user, which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
schema: schema:
type: object type: object
allOf: allOf:
@ -258,12 +249,12 @@ paths:
submit_url: submit_url:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client An optional field containing a URL where the client must
must submit a validation token to, with identical submit the validation token to, with identical parameters
parameters to the Identity Service API's to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver ``/validate/email/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user (if applicable), which
prompted to provide it to the client. should then be prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
verification will happen without the client's verification will happen without the client's
@ -300,10 +291,10 @@ paths:
post: post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |- description: |-
The homeserver should check that the given phone number is **not** The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. The homeserver already associated with an account on this homeserver. The homeserver
has the choice of validating the phone number itself, or proxying the has the choice of validating the phone number itself, or proxying the
request to the ``validate/msisdn/requestToken`` Identity Server API. 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 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 the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts. trusted Identity Servers and only proxies to those it trusts.
@ -327,18 +318,9 @@ paths:
responses: responses:
200: 200:
description: |- description: |-
An SMS message has been sent to the specified phone number. A SMS message has been sent to the specified phone number. Note
Note that this may be an SMS message containing the validation token or it may be informing that this may be an SMS message containing the validation token or
the user of an error. it may be informing the user of an error.
``submit_url`` is an optional field containing a URL where the
client must submit a validation token to, with identical parameters
to the Identity Service API's ``/validate/msisdn/submitToken``
endpoint. The homeserver will send this token to the user, which
should then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement.
schema: schema:
type: object type: object
allOf: allOf:
@ -348,12 +330,12 @@ paths:
submit_url: submit_url:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client An optional field containing a URL where the client must
must submit a validation token to, with identical submit the validation token to, with identical parameters
parameters to the Identity Service API's to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver ``/validate/email/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user (if applicable), which
prompted to provide it to the client. should then be prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
verification will happen without the client's verification will happen without the client's
@ -443,17 +425,17 @@ paths:
post: post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
description: |- description: |-
The homeserver should check that the given email address **is The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the used to request validation tokens when authenticating for the
``account/password`` endpoint. ``account/password`` endpoint.
This API's parameters and response are identical to that of the HS API This API's parameters and response are identical to that of the
|/register/email/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` |/register/email/requestToken|_ endpoint, except that
may be returned if no account matching the given email address could be ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
found. The server may instead send an email to the given address given email address could be found. The server may instead send an
prompting the user to create an account. ``M_THREEPID_IN_USE`` may not email to the given address prompting the user to create an account.
be returned. ``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the email address itself, The homeserver has the choice of validating the email address itself,
or proxying the request to the ``validate/email/requestToken`` Identity or proxying the request to the ``validate/email/requestToken`` Identity
@ -496,11 +478,11 @@ paths:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client must An optional field containing a URL where the client must
submit a validation token to, with identical parameters submit the validation token to, with identical parameters
to the Identity Service API's to the Identity Service API's
``/validate/email/submitToken`` endpoint. The homeserver ``/validate/email/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user (if applicable), which
prompted to provide it to the client. should then be prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
verification will happen without the client's verification will happen without the client's
@ -532,17 +514,17 @@ paths:
post: post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
description: |- description: |-
The homeserver should check that the given phone number **is The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the used to request validation tokens when authenticating for the
``account/password`` endpoint. ``account/password`` endpoint.
This API's parameters and response are identical to that of the HS API This API's parameters and response are identical to that of the
|/register/msisdn/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` may |/register/msisdn/requestToken|_ endpoint, except that
be returned if no account matching the given phone number could be ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
found. The server may instead send the SMS to the given phone number given phone number could be found. The server may instead send the SMS
prompting the user to create an account. ``M_THREEPID_IN_USE`` may not to the given phone number prompting the user to create an account.
be returned. ``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the phone number itself, The homeserver has the choice of validating the phone number itself,
or proxying the request to the ``validate/msisdn/requestToken`` Identity or proxying the request to the ``validate/msisdn/requestToken`` Identity
@ -573,7 +555,7 @@ paths:
required: ['id_server'] required: ['id_server']
responses: responses:
200: 200:
description: An SMS message was sent to the given phone number. description: A SMS message was sent to the given phone number.
schema: schema:
type: object type: object
allOf: allOf:
@ -584,11 +566,11 @@ paths:
type: string type: string
description: |- description: |-
An optional field containing a URL where the client must An optional field containing a URL where the client must
submit a validation token to, with identical parameters submit the validation token to, with identical parameters
to the Identity Service API's to the Identity Service API's
``/validate/msisdn/submitToken`` endpoint. The homeserver ``/validate/msisdn/submitToken`` endpoint. The homeserver
will send this token to the user, which should then be must send this token to the user (if applicable), which
prompted to provide it to the client. should then be prompted to provide it to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
verification will happen without the client's verification will happen without the client's