wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clean up and flesh out all three editions of the /requestToken API

Browse source 
Fixes https://github.com/matrix-org/matrix-doc/issues/1634

Addresses some of https://github.com/matrix-org/matrix-doc/issues/1396
This commit is contained in:
Travis Ralston 2018-08-30 18:18:08 -06:00
parent 2f55dd66da
commit dfaed5b525
7 changed files with 306 additions and 162 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -185,29 +185,105 @@ paths:
- User data
"/account/3pid/email/requestToken":
post:
summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account
summary: Begins the validation process for an email address for association with the user's account.
description: |-
Proxies the identity server API ``validate/email/requestToken``, but
Proxies the identity service API ``validate/email/requestToken``, but
first checks that the given email address is **not** already associated
with an account on this Home Server. This API should be used to request
validation tokens when adding an email address to an account. This API's
parameters and response is identical to that of the HS API
parameters and response is identical to that of the client-server API
|/register/email/requestToken|_ endpoint.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An email was sent to the given address.
schema:
$ref: "../identity/definitions/sid.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
The homeserver was unable to location a user with the third party identifier
alrady bound, or the request was invalid.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Third party identifier not found"
}
"/account/3pid/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account.
summary: Begins the validation process for a phone number for association with the user's account.
description: |-
Proxies the identity server API ``validate/msisdn/requestToken``, but
Proxies the identity service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is **not** already associated
with an account on this Home Server. This API should be used to request
validation tokens when adding a phone number to an account. This API's
parameters and response is identical to that of the HS API
parameters and response is identical to that of the client-server API
|/register/msisdn/requestToken|_ endpoint.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
The homeserver was unable to location a user with the third party identifier
alrady bound, or the request was invalid.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Third party identifier not found"
}

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

@ -192,111 +192,106 @@ paths:
- User data
"/register/email/requestToken":
post:
summary: Requests a validation token be sent to the given email address for the purpose of registering an account
summary: Begins the validation process for an email to be used during registration.
description: |-
Proxies the identity server API ``validate/email/requestToken``, but
Proxies the identity service API ``validate/email/requestToken``, but
first checks that the given email address is not already associated
with an account on this Home Server. See the Identity Server API for
with an account on this homeserver. See the Identity Service API for
further information.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
example: "id.matrix.org"
client_secret:
type: string
description: Client-generated secret string used to protect this session
example: "this_is_my_secret_string"
email:
type: string
description: The email address
example: "example@example.com"
send_attempt:
type: integer
description: Used to distinguish protocol level retries from requests to re-send the email.
example: 1
required: ["client_secret", "email", "send_attempt"]
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: |-
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
the user of an error.
examples:
application/json: {}
schema:
type: object
$ref: "../identity/definitions/sid.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server.
However, if the home server has the ability to send email, it is recommended that the server
However, if the homeserver has the ability to send email, it is recommended that the server
instead send an email to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given email address
has an account on the Home Server in question.
has an account on the homeserver in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
that is not trusted by this Home Server.
that is not trusted by this homeserver.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/register/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |-
Proxies the identity server API ``validate/msisdn/requestToken``, but
Proxies the identity service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is not already associated
with an account on this Home Server. See the Identity Server API for
with an account on this homeserver. See the Identity Service API for
further information.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
example: "id.matrix.org"
client_secret:
type: string
description: Client-generated secret string used to protect this session.
example: "this_is_my_secret_string"
country:
type: string
description: |-
The two-letter uppercase ISO country code that the number in
``phone_number`` should be parsed as if it were dialled from.
phone_number:
type: string
description: The phone number.
example: "example@example.com"
send_attempt:
type: integer
description: Used to distinguish protocol level retries from requests to re-send the SMS message.
example: 1
required: ["client_secret", "country", "phone_number", "send_attempt"]
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: |-
An SMS message has been sent to the specified phone number.
Note that this may be an SMS message containing the validation token or it may be informing
the user of an error.
examples:
application/json: {}
schema:
type: object
$ref: "../identity/definitions/sid.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -310,9 +305,9 @@ paths:
that is not trusted by this Home Server.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/account/password":
@ -368,7 +363,7 @@ paths:
post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
description: |-
Proxies the identity server API ``validate/email/requestToken``, but
Proxies the identity service API ``validate/email/requestToken``, but
first checks that the given email address **is** associated with an account
on this Home Server. This API should be used to request
validation tokens when authenticating for the
@ -383,14 +378,32 @@ paths:
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordEmail
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An email was sent to the given address
schema:
$ref: "../identity/definitions/sid.yaml"
"/account/password/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
description: |-
Proxies the identity server API ``validate/msisdn/requestToken``, but
Proxies the identity service API ``validate/msisdn/requestToken``, but
first checks that the given phone number **is** associated with an account
on this Home Server. This API should be used to request
validation tokens when authenticating for the
@ -405,9 +418,27 @@ paths:
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordMSISDN
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity service to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
"/account/deactivate":
post:
summary: "Deactivate a user's account."
@ -495,7 +526,7 @@ paths:
be ``true`` when the server replies with 200 OK.
400:
description: |-
Part of the request was invalid or the username is not available. This may
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
* ``M_USER_IN_USE`` : The desired username is already taken.

47
api/identity/definitions/request_email_validation.yaml Normal file
View file

@ -0,0 +1,47 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt.
example: "monkeys_are_GREAT"
email:
type: string
description: The email address to validate.
example: "alice@example.org"
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an email if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``email`` + ``client_secret`` pair. This is to avoid
repeatedly sending the same email in the case of request
retries between the POSTing user and the identity
service. The client should increment this value if they
desire a new email (e.g. a reminder) to be sent.
example: 1
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
example: "https://example.org/congratulations.html"
required: ["client_secret", "email", "send_attempt"]

54
api/identity/definitions/request_msisdn_validation.yaml Normal file
View file

@ -0,0 +1,54 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"country": "GB",
"phone_number": "07700900001",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt.
example: "monkeys_are_GREAT"
country:
type: string
description: |-
The two-letter uppercase ISO country code that the number in
``phone_number`` should be parsed as if it were dialled from.
example: "GB"
phone_number:
type: string
description: The phone number to validate.
example: "07700900001"
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an SMS if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``country`` + ``phone_number`` + ``client_secret``
triple. This is to avoid repeatedly sending the same SMS in
the case of request retries between the POSTing user and the
identity service. The client should increment this value if
they desire a new SMS (e.g. a reminder) to be sent.
example: 1
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
example: "https://example.org/congratulations.html"
required: ["client_secret", "country", "phone_number", "send_attempt"]

20
api/identity/definitions/sid.yaml Normal file
View file

@ -0,0 +1,20 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
properties:
sid:
type: string
description: The session ID.
example: "123abc"
required: ['sid']

45
api/identity/email_associations.yaml
View file

@ -50,51 +50,12 @@ paths:
- in: body
name: body
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt.
email:
type: string
description: The email address to validate.
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an email if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``email`` + ``client_secret`` pair. This is to avoid
repeatedly sending the same email in the case of request
retries between the POSTing user and the identity
service. The client should increment this value if they
desire a new email (e.g. a reminder) to be sent.
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
required: ["client_secret", "email"]
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description:
Session created.
examples:
application/json: {
"sid": "1234"
}
description: Session created.
schema:
type: object
properties:
sid:
type: string
description: The session ID.
required: ['sid']
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are:

51
api/identity/phone_associations.yaml
View file

@ -50,57 +50,12 @@ paths:
- in: body
name: body
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"country": "GB",
"phone_number": "07700900001",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt.
country:
type: string
description: |-
The two-letter uppercase ISO country code that the number in
``phone_number`` should be parsed as if it were dialled from.
phone_number:
type: string
description: The phone number to validate.
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an SMS if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``country`` + ``phone_number`` + ``client_secret``
triple. This is to avoid repeatedly sending the same SMS in
the case of request retries between the POSTing user and the
identity service. The client should increment this value if
they desire a new SMS (e.g. a reminder) to be sent.
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
required: ["client_secret", "country", "phone_number"]
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description:
Session created.
examples:
application/json: {
"sid": "1234"
}
description: Session created.
schema:
type: object
properties:
sid:
type: string
description: The session ID.
required: ['sid']
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are: