matrix-spec/api/identity/phone_associations.yaml

# 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.
swagger: '2.0'
info:
  title: "Matrix Identity Service Phone Number Associations API"
  version: "1.0.0"
host: localhost:8090
schemes:
  - https
  - http
basePath: /_matrix/identity/api/v1
produces:
  - application/json
paths:
  "/validate/msisdn/requestToken":
    post:
      summary: Request a token for validating a phone number.
      description: |-
        Create a session for validating a phone number.

        The identity service will send an SMS message containing a token. If
        that token is presented to the identity service in the future, it
        indicates that that user was able to read the SMS for that phone
        number, and so we validate ownership of the phone number.

        Note that Home Servers offer APIs that proxy this API, adding
        additional behaviour on top, for example,
        ``/register/msisdn/requestToken`` is designed specifically for use when
        registering an account and therefore will inform the user if the phone
        number given is already registered on the server.

        Note: for backwards compatibility with older versions of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data. However, this usage is
        deprecated.
      operationId: msisdnRequestToken
      parameters:
        - 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"]
      responses:
        200:
          description:
            Session created.
          examples:
            application/json: {
                "sid": "1234"
              }
          schema:
            type: object
            properties:
              sid:
                type: string
                description: The session ID.
        400:
          description: |
            An error ocurred. Some possible errors are:

            - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
            - ``M_SEND_ERROR``: The validation SMS could not be sent.
  "/validate/msisdn/submitToken":
    post:
      summary: Validate ownership of a phone number.
      description: |-
        Validate ownership of a phone number.

        If the three parameters are consistent with a set generated by a
        ``requestToken`` call, ownership of the phone number is considered to
        have been validated. This does not publish any information publicly, or
        associate the phone number address with any Matrix user
        ID. Specifically, calls to ``/lookup`` will not show a binding.

        Note: for backwards compatibility with older versions of this
        specification, the parameters may also be specified as
        ``application/x-form-www-urlencoded`` data. However, this usage is
        deprecated.
      operationId: msisdnSubmitTokenPost
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: {
                "sid": "1234",
                "client_secret": "monkeys_are_GREAT",
                "token": "atoken"
              }
            properties:
              sid:
                type: string
                description: The session ID, generated by the ``requestToken`` call.
              client_secret:
                type: string
                description: The client secret that was supplied to the ``requestToken`` call.
              token:
                type: string
                description: The token generated by the ``requestToken`` call and sent to the user.
            required: ["sid", "client_secret", "token"]
      responses:
        200:
          description:
            The success of the validation.
          examples:
            application/json: {
                "success": true
              }
          schema:
            type: object
            properties:
              success:
                type: boolean
                description: Whether the validation was successful or not.
    get:
      summary: Validate ownership of a phone number.
      description: |-
        Validate ownership of a phone number.

        If the three parameters are consistent with a set generated by a
        ``requestToken`` call, ownership of the phone number address is
        considered to have been validated. This does not publish any
        information publicly, or associate the phone number with any Matrix
        user ID. Specifically, calls to ``/lookup`` will not show a binding.

        Note that, in contrast with the POST version, this endpoint will be
        used by end-users, and so the response should be human-readable.
      operationId: msisdnSubmitTokenGet
      parameters:
        - in: query
          type: string
          name: sid
          required: true
          description: The session ID, generated by the ``requestToken`` call.
          x-example: 1234
        - in: query
          type: string
          name: client_secret
          required: true
          description: The client secret that was supplied to the ``requestToken`` call.
          x-example: monkeys_are_GREAT
        - in: query
          type: string
          name: token
          required: true
          description: The token generated by the ``requestToken`` call and sent to the user.
          x-example: atoken
      responses:
        "200":
          description: Phone number is validated.
        "3xx":
          description: |-
            Phone number address is validated, and the ``next_link`` parameter
            was provided to the ``requestToken`` call. The user must be
            redirected to the URL provided by the ``next_link`` parameter.
        "4xx":
          description:
            Validation failed.