matrix-spec/data/api/identity/v2_email_associations.yaml

# Copyright 2018 New Vector 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.
# 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.
openapi: 3.1.0
info:
  title: Matrix Identity Service Email Associations API
  version: 2.0.0
paths:
  /validate/email/requestToken:
    post:
      summary: Request a token for validating an email address.
      description: |-
        Create a session for validating an email address.

        The identity server will send an email containing a token. If that
        token is presented to the identity server in the future, it indicates
        that that user was able to read the email for that email address, and
        so we validate ownership of the email address.

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

        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        `application/x-form-www-urlencoded` data.  However, this usage is
        deprecated.
      operationId: emailRequestTokenV2
      security:
        - accessToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: definitions/request_email_validation.yaml
      responses:
        "200":
          description: Session created.
          content:
            application/json:
              schema:
                $ref: definitions/sid.yaml
        "400":
          description: |
            An error occurred.  Some possible errors are:

            - `M_INVALID_EMAIL`: The email address provided was invalid.
            - `M_EMAIL_SEND_ERROR`: The validation email could not be sent.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_INVALID_EMAIL",
                    "error": "The email address is not valid"
                  }
        "403":
          description: |
            The user must do something in order to use this endpoint. One example
            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_TERMS_NOT_SIGNED",
                    "error": "Please accept our updated terms of service before continuing"
                  }
  /validate/email/submitToken:
    post:
      summary: Validate ownership of an email address.
      description: |-
        Validate ownership of an email address.

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

        The identity server is free to match the token case-insensitively, or
        carry out other mapping operations such as unicode
        normalisation. Whether to do so is an implementation detail for the
        identity server. Clients must always pass on the token without
        modification.

        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        `application/x-form-www-urlencoded` data.  However, this usage is
        deprecated.
      operationId: emailSubmitTokenPostV2
      security:
        - accessToken: []
      requestBody:
        content:
          application/json:
            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 emailed to the
                    user.
              required:
                - sid
                - client_secret
                - token
      responses:
        "200":
          description: The success of the validation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the validation was successful or not.
                required:
                  - success
              examples:
                response:
                  value: {
                    "success": true
                  }
        "403":
          description: |
            The user must do something in order to use this endpoint. One example
            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_TERMS_NOT_SIGNED",
                    "error": "Please accept our updated terms of service before continuing"
                  }
    get:
      summary: Validate ownership of an email address.
      description: |-
        Validate ownership of an email address.

        If the three parameters are consistent with a set generated by a
        `requestToken` call, ownership of the email address is considered to
        have been validated. This does not publish any information publicly, or
        associate the email address 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: emailSubmitTokenGetV2
      security:
        - accessToken: []
      parameters:
        - in: query
          name: sid
          required: true
          description: The session ID, generated by the `requestToken` call.
          example: "1234"
          schema:
            type: string
        - in: query
          name: client_secret
          required: true
          description: The client secret that was supplied to the `requestToken` call.
          example: monkeys_are_GREAT
          schema:
            type: string
        - in: query
          name: token
          required: true
          description: The token generated by the `requestToken` call and emailed to the
            user.
          example: atoken
          schema:
            type: string
      responses:
        "200":
          description: Email address is validated.
        "403":
          description: |
            The user must do something in order to use this endpoint. One example
            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_TERMS_NOT_SIGNED",
                    "error": "Please accept our updated terms of service before continuing"
                  }
        "3XX":
          description: |-
            Email 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.
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8090
      basePath:
        default: /_matrix/identity/v2
components:
  securitySchemes:
    $ref: definitions/security.yaml