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.
333 lines
13 KiB
YAML
333 lines
13 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.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Identity Service Establishing Associations API"
|
|
version: "2.0.0"
|
|
host: localhost:8090
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/identity/v2
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/3pid/getValidated3pid":
|
|
get:
|
|
summary: Check whether ownership of a 3pid was validated.
|
|
description: |-
|
|
Determines if a given 3pid has been validated by a user.
|
|
operationId: getValidated3pidV2
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: query
|
|
type: string
|
|
name: sid
|
|
description: The Session ID generated by the ``requestToken`` call.
|
|
required: true
|
|
x-example: 1234
|
|
- in: query
|
|
type: string
|
|
name: client_secret
|
|
description: The client secret passed to the ``requestToken`` call.
|
|
required: true
|
|
x-example: monkeys_are_GREAT
|
|
responses:
|
|
200:
|
|
description: Validation information for the session.
|
|
examples:
|
|
application/json: {
|
|
"medium": "email",
|
|
"validated_at": 1457622739026,
|
|
"address": "louise@bobs.burgers"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
medium:
|
|
type: string
|
|
description: The medium type of the 3pid.
|
|
address:
|
|
type: string
|
|
description: The address of the 3pid being looked up.
|
|
validated_at:
|
|
type: integer
|
|
description: |-
|
|
Timestamp, in milliseconds, indicating the time that the 3pid
|
|
was validated.
|
|
required: ['medium', 'address', 'validated_at']
|
|
400:
|
|
description: |-
|
|
The session has not been validated.
|
|
|
|
If the session has not been validated, then ``errcode`` will be
|
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
|
"error": "This validation session has not yet been completed"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
404:
|
|
description: The Session ID or client secret were not found.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_NO_VALID_SESSION",
|
|
"error": "No valid session was found matching that sid and client secret"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
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`_.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_TERMS_NOT_SIGNED",
|
|
"error": "Please accept our updated terms of service before continuing"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
"/3pid/bind":
|
|
post:
|
|
summary: Publish an association between a session and a Matrix user ID.
|
|
description: |-
|
|
Publish an association between a session and a Matrix user ID.
|
|
|
|
Future calls to ``/lookup`` for any of the session\'s 3pids will return
|
|
this association.
|
|
|
|
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: bindV2
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"sid": "1234",
|
|
"client_secret": "monkeys_are_GREAT",
|
|
"mxid": "@ears:matrix.org"
|
|
}
|
|
properties:
|
|
sid:
|
|
type: string
|
|
description: The Session ID generated by the ``requestToken`` call.
|
|
client_secret:
|
|
type: string
|
|
description: The client secret passed to the ``requestToken`` call.
|
|
mxid:
|
|
type: string
|
|
description: The Matrix user ID to associate with the 3pids.
|
|
required: ["sid", "client_secret", "mxid"]
|
|
responses:
|
|
200:
|
|
description: The association was published.
|
|
examples:
|
|
application/json: {
|
|
"address": "louise@bobs.burgers",
|
|
"medium": "email",
|
|
"mxid": "@ears:matrix.org",
|
|
"not_before": 1428825849161,
|
|
"not_after": 4582425849161,
|
|
"ts": 1428825849161,
|
|
"signatures": {
|
|
"matrix.org": {
|
|
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
|
|
}
|
|
}
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
address:
|
|
type: string
|
|
description: The 3pid address of the user being looked up.
|
|
medium:
|
|
type: string
|
|
description: The medium type of the 3pid.
|
|
mxid:
|
|
type: string
|
|
description: The Matrix user ID associated with the 3pid.
|
|
not_before:
|
|
type: integer
|
|
description: A unix timestamp before which the association is not known to be valid.
|
|
not_after:
|
|
type: integer
|
|
description: A unix timestamp after which the association is not known to be valid.
|
|
ts:
|
|
type: integer
|
|
description: The unix timestamp at which the association was verified.
|
|
signatures:
|
|
type: object
|
|
description: |-
|
|
The signatures of the verifying identity servers which show that the
|
|
association should be trusted, if you trust the verifying identity
|
|
services.
|
|
$ref: "../../schemas/server-signatures.yaml"
|
|
required:
|
|
- address
|
|
- medium
|
|
- mxid
|
|
- not_before
|
|
- not_after
|
|
- ts
|
|
- signatures
|
|
400:
|
|
description: |-
|
|
The association was not published.
|
|
|
|
If the session has not been validated, then ``errcode`` will be
|
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
|
"error": "This validation session has not yet been completed"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
404:
|
|
description: The Session ID or client secret were not found
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_NO_VALID_SESSION",
|
|
"error": "No valid session was found matching that sid and client secret"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
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`_.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_TERMS_NOT_SIGNED",
|
|
"error": "Please accept our updated terms of service before continuing"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
"/3pid/unbind":
|
|
post:
|
|
summary: Remove an association between a session and a Matrix user ID.
|
|
description: |-
|
|
Remove an association between a session and a Matrix user ID.
|
|
|
|
Future calls to ``/lookup`` for any of the session's 3pids will not
|
|
return the removed association.
|
|
|
|
The identity server should authenticate the request in one of two
|
|
ways:
|
|
|
|
1. The request is signed by the homeserver which controls the ``user_id``.
|
|
2. The request includes the ``sid`` and ``client_secret`` parameters,
|
|
as per ``/3pid/bind``, which proves ownership of the 3PID.
|
|
|
|
If this endpoint returns a JSON Matrix error, that error should be passed
|
|
through to the client requesting an unbind through a homeserver, if the
|
|
homeserver is acting on behalf of a client.
|
|
operationId: unbindV2
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"sid": "1234",
|
|
"client_secret": "monkeys_are_GREAT",
|
|
"mxid": "@ears:example.org",
|
|
"threepid": {
|
|
"medium": "email",
|
|
"address": "monkeys_have_ears@example.org"
|
|
}
|
|
}
|
|
properties:
|
|
sid:
|
|
type: string
|
|
description: The Session ID generated by the ``requestToken`` call.
|
|
client_secret:
|
|
type: string
|
|
description: The client secret passed to the ``requestToken`` call.
|
|
mxid:
|
|
type: string
|
|
description: The Matrix user ID to remove from the 3pids.
|
|
threepid:
|
|
type: object
|
|
title: 3PID
|
|
description: |-
|
|
The 3PID to remove. Must match the 3PID used to generate the session
|
|
if using ``sid`` and ``client_secret`` to authenticate this request.
|
|
properties:
|
|
medium:
|
|
type: string
|
|
description: |-
|
|
A medium from the `3PID Types`_ Appendix, matching the medium
|
|
of the identifier to unbind.
|
|
address:
|
|
type: string
|
|
description: The 3PID address to remove.
|
|
required: ['medium', 'address']
|
|
required: ["threepid", "mxid"]
|
|
responses:
|
|
200:
|
|
description: The association was successfully removed.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
400:
|
|
description: |-
|
|
If the response body is not a JSON Matrix error, the identity server
|
|
does not support unbinds. If a JSON Matrix error is in the response
|
|
body, the requesting party should respect the error.
|
|
404:
|
|
description: |-
|
|
If the response body is not a JSON Matrix error, the identity server
|
|
does not support unbinds. If a JSON Matrix error is in the response
|
|
body, the requesting party should respect the error.
|
|
403:
|
|
description: |-
|
|
The credentials supplied to authenticate the request were invalid.
|
|
This may also be returned if the identity server does not support
|
|
the chosen authentication method (such as blocking homeservers from
|
|
unbinding identifiers).
|
|
|
|
Another common error code is ``M_TERMS_NOT_SIGNED`` where the user
|
|
needs to `agree to more terms`_ in order to continue.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Invalid homeserver signature"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
501:
|
|
description: |-
|
|
If the response body is not a JSON Matrix error, the identity server
|
|
does not support unbinds. If a JSON Matrix error is in the response
|
|
body, the requesting party should respect the error.
|