matrix-doc/api/client-server/administrative_contact.yaml

294 lines
11 KiB
YAML
Raw Permalink Normal View History

# 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.
2015-12-01 13:53:03 +00:00
swagger: '2.0'
info:
title: "Matrix Client-Server Account Administrative Contact API"
2015-12-01 13:53:03 +00:00
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
2015-12-01 13:53:03 +00:00
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
2015-12-01 13:53:03 +00:00
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.
2015-12-01 13:53:03 +00:00
Identifiers in this list may be used by the homeserver as, for example,
2015-12-01 13:53:03 +00:00
identifiers that it will accept to reset the user's account password.
operationId: getAccount3PIDs
2015-12-01 13:53:03 +00:00
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
}
]
}
2015-12-01 13:53:03 +00:00
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"]
2015-12-01 13:53:03 +00:00
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
2015-12-01 13:53:03 +00:00
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
operationId: post3PIDs
2015-12-01 13:53:03 +00:00
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
three_pid_creds:
2015-12-01 13:53:03 +00:00
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.
2015-12-01 13:53:03 +00:00
id_server:
type: string
description: The identity server to use.
2015-12-01 13:53:03 +00:00
sid:
type: string
description: The session identifier given by the identity server.
2015-12-01 13:53:03 +00:00
required: ["client_secret", "id_server", "sid"]
bind:
type: boolean
description: |-
Whether the homeserver should also bind this third party
2015-12-01 13:53:03 +00:00
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": {
2015-12-01 13:53:03 +00:00
"id_server": "matrix.org",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
},
"bind": false
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
2015-12-01 13:53:03 +00:00
schema:
type: object
403:
description: The credentials could not be verified with the identity server.
2015-12-01 13:53:03 +00:00
examples:
application/json: {
2015-12-01 13:53:03 +00:00
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
2015-12-01 13:53:03 +00:00
}
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:
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
2018-08-30 21:28:43 +00:00
properties: {}
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: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address is **not** already associated
with an account on this homeserver. This API should be used to request
2016-07-07 16:07:38 +00:00
validation tokens when adding an email address to an account. This API's
2018-08-31 17:31:03 +00:00
parameters and response are identical to that of the |/register/email/requestToken|_
endpoint.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An email was sent to the given address.
schema:
$ref: "../identity/definitions/sid.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: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks 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
2018-08-31 17:31:03 +00:00
parameters and response are identical to that of the |/register/msisdn/requestToken|_
endpoint.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.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"
}