afd5018494
Part of MSC2140 Convert status codes to strings if there is a string status code. Fixes a build error when we mix 4xx and 403 in the same definition. We also have to correct stringified numbers to pass the build.
177 lines
6.6 KiB
YAML
177 lines
6.6 KiB
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 Email Associations API"
|
|
version: "1.0.0"
|
|
host: localhost:8090
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/identity/api/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
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: emailRequestToken
|
|
deprecated: true
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
$ref: "definitions/request_email_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: Session created.
|
|
schema:
|
|
$ref: "definitions/sid.yaml"
|
|
400:
|
|
description: |
|
|
An error ocurred. Some possible errors are:
|
|
|
|
- ``M_INVALID_EMAIL``: The email address provided was invalid.
|
|
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_INVALID_EMAIL",
|
|
"error": "The email address is not valid"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
"/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: emailSubmitTokenPost
|
|
deprecated: true
|
|
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 emailed 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.
|
|
required: ['success']
|
|
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: emailSubmitTokenGet
|
|
deprecated: true
|
|
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 emailed to the user.
|
|
x-example: atoken
|
|
responses:
|
|
200:
|
|
description: Email address is validated.
|
|
"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.
|