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.
328 lines
13 KiB
YAML
328 lines
13 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 server.
|
|
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: {
|
|
"submit_url": "https://example.org/path/to/submitToken"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client must
|
|
submit the validation token to, with identical parameters
|
|
to the Identity Service API's ``POST
|
|
/validate/email/submitToken`` endpoint. The homeserver must
|
|
send this token to the user (if applicable), who should
|
|
then be prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's involvement
|
|
provided the homeserver advertises this specification version
|
|
in the ``/versions`` response (ie: r0.5.0).
|
|
example: "https://example.org/path/to/submitToken"
|
|
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 might not
|
|
cause an unbind of the identifier from the identity server.
|
|
operationId: delete3pidFromAccount
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The identity server to unbind from. If not provided, the homeserver
|
|
MUST use the ``id_server`` the identifier was added through. If the
|
|
homeserver does not know the original ``id_server``, it MUST return
|
|
a ``id_server_unbind_result`` of ``no-support``.
|
|
example: "example.org"
|
|
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@example.org"
|
|
required: ['medium', 'address']
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The homeserver has disassociated the third party identifier from the
|
|
user.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server_unbind_result:
|
|
type: string
|
|
enum:
|
|
# XXX: I don't know why, but the order matters here so that "no-support"
|
|
# doesn't become "no- support" by the renderer.
|
|
- "no-support"
|
|
- "success"
|
|
description: |-
|
|
An indicator as to whether or not the homeserver was able to unbind
|
|
the 3PID from the identity server. ``success`` indicates that the
|
|
indentity server has unbound the identifier whereas ``no-support``
|
|
indicates that the identity server refuses to support the request
|
|
or the homeserver was not able to determine an identity server to
|
|
unbind from.
|
|
example: "success"
|
|
required:
|
|
- id_server_unbind_result
|
|
tags:
|
|
- User data
|
|
"/account/3pid/email/requestToken":
|
|
post:
|
|
summary: Begins the validation process for an email address for association with the user's account.
|
|
description: |-
|
|
The homeserver must check that the given email address is **not**
|
|
already associated with an account on this homeserver. This API should
|
|
be used to request validation tokens when adding an email address to an
|
|
account. This API's parameters and response are identical to that of
|
|
the |/register/email/requestToken|_ endpoint. The homeserver has the
|
|
choice of validating the email address itself, or proxying the request
|
|
to the ``/validate/email/requestToken`` Identity Service API as
|
|
identified by ``id_server``. It is imperative that the
|
|
homeserver keep a list of trusted Identity Servers and only proxies to
|
|
those that it trusts.
|
|
operationId: requestTokenTo3PIDEmail
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "./definitions/request_email_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: |-
|
|
An email was sent to the given address. Note that this may be an
|
|
email containing the validation token or it may be informing the
|
|
user of an error.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
403:
|
|
description: |-
|
|
The homeserver does not allow the third party identifier as a
|
|
contact option.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
description: |-
|
|
The third party identifier is already in use on the homeserver, or
|
|
the request was invalid.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third party identifier already in use"
|
|
}
|
|
"/account/3pid/msisdn/requestToken":
|
|
post:
|
|
summary: Begins the validation process for a phone number for association with the user's account.
|
|
description: |-
|
|
The homeserver must check that the given phone number is **not**
|
|
already associated with an account on this homeserver. This API should
|
|
be used to request validation tokens when adding a phone number to an
|
|
account. This API's parameters and response are identical to that of
|
|
the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
|
|
choice of validating the phone number itself, or proxying the request
|
|
to the ``/validate/msisdn/requestToken`` Identity Service API as
|
|
identified by ``id_server``. It is imperative that the
|
|
homeserver keep a list of trusted Identity Servers and only proxies to
|
|
those that it trusts.
|
|
operationId: requestTokenTo3PIDMSISDN
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "./definitions/request_msisdn_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: An SMS message was sent to the given phone number.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
403:
|
|
description: |-
|
|
The homeserver does not allow the third party identifier as a
|
|
contact option.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
description: |-
|
|
The third party identifier is already in use on the homeserver, or
|
|
the request was invalid.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third party identifier already in use"
|
|
}
|