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.
matrix-spec-proposals/api/client-server/administrative_contact.yaml

294 lines
11 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: {}
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 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
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
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.
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
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"
}