# 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 Establishing Associations API"
version : "1.0.0"
host : localhost:8090
schemes :
- https
- http
basePath : /_matrix/identity/api/v1
produces :
- application/json
paths :
"/3pid/getValidated3pid" :
get :
summary : Check whether ownership of a 3pid was validated.
description : A client can check whether ownership of a 3pid was validated
operationId : getValidated3pid
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 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"
"/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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId : bind
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 services 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"
