# 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.