You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/identity/v2_phone_associations.yaml

247 lines
9.3 KiB
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 Phone Number Associations API
version: 2.0.0
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 server will send an SMS message 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 SMS for that phone
number, and so we validate ownership of the phone number.
Note that homeservers 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 previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestTokenV2
security:
- accessToken: []
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_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_ADDRESS`: The phone number provided was invalid.
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number 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/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.
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: msisdnSubmitTokenPostV2
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 sent 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 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: msisdnSubmitTokenGetV2
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 sent to the user.
example: atoken
schema:
type: string
responses:
"200":
description: Phone number 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: |-
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.
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