mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 09:58:38 +01:00
7bd48ca9c7
If an object definition already has an example, we shouldn't try to extend that definition by adding examples derived from the individual properties. Doing so is confusing, and there is no way to inhibit it when it is not desired. It's also not what the RapiDoc viewere does, so we end up with examples being inconsistent.
523 lines
20 KiB
YAML
523 lines
20 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
# Copyright 2019 The Matrix.org Foundation C.I.C.
|
|
#
|
|
# 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/v3
|
|
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:
|
|
- Account management
|
|
post:
|
|
summary: Adds contact information to the user's account.
|
|
description: |-
|
|
Adds contact information to the user's account.
|
|
|
|
This endpoint is deprecated in favour of the more specific `/3pid/add`
|
|
and `/3pid/bind` endpoints.
|
|
|
|
**Note:**
|
|
Previously this endpoint supported a `bind` parameter. This parameter
|
|
has been removed, making this endpoint behave as though it was `false`.
|
|
This results in this endpoint being an equivalent to `/3pid/bind` rather
|
|
than dual-purpose.
|
|
operationId: post3PIDs
|
|
deprecated: true
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
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.
|
|
id_access_token:
|
|
type: string
|
|
description: |-
|
|
An access token previously registered with the identity server. Servers
|
|
can treat this as optional to distinguish between r0.5-compatible clients
|
|
and this specification version.
|
|
sid:
|
|
type: string
|
|
description: The session identifier given by the identity server.
|
|
required: ["client_secret", "id_server", "id_access_token", "sid"]
|
|
required: ["three_pid_creds"]
|
|
example: {
|
|
"three_pid_creds": {
|
|
"id_server": "matrix.org",
|
|
"id_access_token": "abc123_OpaqueString",
|
|
"sid": "abc123987",
|
|
"client_secret": "d0nt-T3ll"
|
|
}
|
|
}
|
|
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
|
|
format: uri
|
|
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 (without the requirement
|
|
for an access token). 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:
|
|
- Account management
|
|
"/account/3pid/add":
|
|
post:
|
|
summary: Adds contact information to the user's account.
|
|
description: |-
|
|
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
|
|
|
Adds contact information to the user's account. Homeservers should use 3PIDs added
|
|
through this endpoint for password resets instead of relying on the identity server.
|
|
|
|
Homeservers should prevent the caller from adding a 3PID to their account if it has
|
|
already been added to another user's account on the homeserver.
|
|
operationId: add3PID
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the
|
|
user-interactive authentication API.
|
|
allOf:
|
|
- $ref: "definitions/auth_data.yaml"
|
|
client_secret:
|
|
type: string
|
|
description: The client secret used in the session with the homeserver.
|
|
example: "d0nt-T3ll"
|
|
sid:
|
|
type: string
|
|
description: The session identifier given by the homeserver.
|
|
example: "abc123987"
|
|
required: ["client_secret", "sid"]
|
|
responses:
|
|
200:
|
|
description: The addition was successful.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
401:
|
|
description: |-
|
|
The homeserver requires additional authentication information.
|
|
schema:
|
|
"$ref": "definitions/auth_response.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- Account management
|
|
"/account/3pid/bind":
|
|
post:
|
|
summary: Binds a 3PID to the user's account through an Identity Service.
|
|
description: |-
|
|
Binds a 3PID to the user's account through the specified identity server.
|
|
|
|
Homeservers should not prevent this request from succeeding if another user
|
|
has bound the 3PID. Homeservers should simply proxy any errors received by
|
|
the identity server to the caller.
|
|
|
|
Homeservers should track successful binds so they can be unbound later.
|
|
operationId: bind3PID
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
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.
|
|
id_access_token:
|
|
type: string
|
|
description: |-
|
|
An access token previously registered with the identity server.
|
|
sid:
|
|
type: string
|
|
description: The session identifier given by the identity server.
|
|
required: ["client_secret", "id_server", "id_access_token", "sid"]
|
|
example: {
|
|
"id_server": "example.org",
|
|
"id_access_token": "abc123_OpaqueString",
|
|
"sid": "abc123987",
|
|
"client_secret": "d0nt-T3ll"
|
|
}
|
|
responses:
|
|
200:
|
|
description: The addition was successful.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- Account management
|
|
"/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.
|
|
|
|
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
|
parameter because the homeserver is expected to sign the request to the
|
|
identity server instead.
|
|
operationId: delete3pidFromAccount
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
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
|
|
identity 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:
|
|
- Account management
|
|
"/account/3pid/unbind":
|
|
post:
|
|
summary: Removes a user's third party identifier from an identity server.
|
|
description: |-
|
|
Removes a user's third party identifier from the provided identity server
|
|
without removing it from the homeserver.
|
|
|
|
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
|
parameter because the homeserver is expected to sign the request to the
|
|
identity server instead.
|
|
operationId: unbind3pidFromAccount
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
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 identity server 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 identity server was able to unbind
|
|
the 3PID. `success` indicates that the identity 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:
|
|
- Account management
|
|
"/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`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
|
|
endpoint. The homeserver should validate
|
|
the email itself, either by sending a validation email itself or by using
|
|
a service it has control over.
|
|
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. The error code `M_SERVER_NOT_TRUSTED`
|
|
can be returned if the server does not trust/support the identity server
|
|
provided in the request.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third party identifier already in use"
|
|
}
|
|
tags:
|
|
- Account management
|
|
"/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`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
|
|
endpoint. The homeserver should validate
|
|
the phone number itself, either by sending a validation message itself or by using
|
|
a service it has control over.
|
|
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. The error code `M_SERVER_NOT_TRUSTED`
|
|
can be returned if the server does not trust/support the identity server
|
|
provided in the request.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third party identifier already in use"
|
|
}
|
|
tags:
|
|
- Account management
|