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.
214 lines
8.0 KiB
YAML
214 lines
8.0 KiB
YAML
# Copyright 2016 OpenMarket 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 Client-Server Account Administrative Contact API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/account/3pid":
|
|
get:
|
|
summary: Gets a list of a user's third party identifiers.
|
|
description: |-
|
|
Gets a list of the third party identifiers that the homeserver has
|
|
associated with the user's account.
|
|
|
|
This is *not* the same as the list of third party identifiers bound to
|
|
the user's Matrix ID in Identity Servers.
|
|
|
|
Identifiers in this list may be used by the homeserver as, for example,
|
|
identifiers that it will accept to reset the user's account password.
|
|
operationId: getAccount3PIDs
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The lookup was successful.
|
|
examples:
|
|
application/json: {
|
|
"threepids": [
|
|
{
|
|
"medium": "email",
|
|
"address": "monkey@banana.island",
|
|
"validated_at": 1535176800000,
|
|
"added_at": 1535336848756
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
threepids:
|
|
type: array
|
|
items:
|
|
type: object
|
|
title: Third party identifier
|
|
properties:
|
|
medium:
|
|
type: string
|
|
description: The medium of the third party identifier.
|
|
enum: ["email", "msisdn"]
|
|
address:
|
|
type: string
|
|
description: The third party identifier address.
|
|
validated_at:
|
|
type: integer
|
|
format: int64
|
|
description: |-
|
|
The timestamp, in milliseconds, when the identifier was
|
|
validated by the identity service.
|
|
added_at:
|
|
type: integer
|
|
format: int64
|
|
description:
|
|
The timestamp, in milliseconds, when the homeserver
|
|
associated the third party identifier with the user.
|
|
required: ['medium', 'address', 'validated_at', 'added_at']
|
|
tags:
|
|
- User data
|
|
post:
|
|
summary: Adds contact information to the user's account.
|
|
description: Adds contact information to the user's account.
|
|
operationId: post3PIDs
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
three_pid_creds:
|
|
title: "ThreePidCredentials"
|
|
type: object
|
|
description: The third party credentials to associate with the account.
|
|
properties:
|
|
client_secret:
|
|
type: string
|
|
description: The client secret used in the session with the Identity Server.
|
|
id_server:
|
|
type: string
|
|
description: The Identity Server to use.
|
|
sid:
|
|
type: string
|
|
description: The session identifier given by the Identity Server.
|
|
required: ["client_secret", "id_server", "sid"]
|
|
bind:
|
|
type: boolean
|
|
description: |-
|
|
Whether the homeserver should also bind this third party
|
|
identifier to the account's Matrix ID with the passed identity
|
|
server. Default: ``false``.
|
|
x-example: true
|
|
required: ["three_pid_creds"]
|
|
example: {
|
|
"three_pid_creds": {
|
|
"id_server": "matrix.org",
|
|
"sid": "abc123987",
|
|
"client_secret": "d0n'tT3ll"
|
|
},
|
|
"bind": false
|
|
}
|
|
responses:
|
|
200:
|
|
description: The addition was successful.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
403:
|
|
description: The credentials could not be verified with the identity server.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_AUTH_FAILED",
|
|
"error": "The third party credentials could not be verified by the identity server."
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
tags:
|
|
- User data
|
|
"/account/3pid/delete":
|
|
post:
|
|
summary: Deletes a third party identifier from the user's account
|
|
description: |-
|
|
Removes a third party identifier from the user's account. This may not
|
|
cause an unbind of the identifier from the identity service.
|
|
operationId: delete3pidFromAccount
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
medium:
|
|
type: string
|
|
description: The medium of the third party identifier being removed.
|
|
enum: ["email", "msisdn"]
|
|
example: "email"
|
|
address:
|
|
type: string
|
|
description: The third party address being removed.
|
|
example: "example@domain.com"
|
|
required: ['medium', 'address']
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The homeserver has disassociated the third party identifier from the
|
|
user.
|
|
schema:
|
|
type: object
|
|
properties: {}
|
|
tags:
|
|
- User data
|
|
"/account/3pid/email/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account
|
|
description: |-
|
|
Proxies the identity server API ``validate/email/requestToken``, but
|
|
first checks that the given email address is **not** already associated
|
|
with an account on this Home Server. This API should be used to request
|
|
validation tokens when adding an email address to an account. This API's
|
|
parameters and response is identical to that of the HS API
|
|
|/register/email/requestToken|_ endpoint.
|
|
operationId: requestTokenTo3PIDEmail
|
|
responses:
|
|
200:
|
|
description: An email was sent to the given address.
|
|
"/account/3pid/msisdn/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account.
|
|
description: |-
|
|
Proxies the identity server API ``validate/msisdn/requestToken``, but
|
|
first checks that the given phone number is **not** already associated
|
|
with an account on this Home Server. This API should be used to request
|
|
validation tokens when adding a phone number to an account. This API's
|
|
parameters and response is identical to that of the HS API
|
|
|/register/msisdn/requestToken|_ endpoint.
|
|
operationId: requestTokenTo3PIDMSISDN
|
|
responses:
|
|
200:
|
|
description: An SMS message was sent to the given phone number.
|