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.
588 lines
22 KiB
YAML
588 lines
22 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.
|
|
openapi: 3.1.0
|
|
info:
|
|
title: Matrix Client-Server Account Administrative Contact API
|
|
version: 1.0.0
|
|
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.
|
|
content:
|
|
application/json:
|
|
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
|
|
examples:
|
|
response:
|
|
value: {
|
|
"threepids": [
|
|
{
|
|
"medium": "email",
|
|
"address": "monkey@banana.island",
|
|
"validated_at": 1535176800000,
|
|
"added_at": 1535336848756
|
|
}
|
|
]
|
|
}
|
|
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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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"
|
|
}
|
|
}
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The addition was successful.
|
|
content:
|
|
application/json:
|
|
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
|
|
examples:
|
|
response:
|
|
value: {
|
|
"submit_url": "https://example.org/path/to/submitToken"
|
|
}
|
|
"403":
|
|
description: The credentials could not be verified with the identity server.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_THREEPID_AUTH_FAILED",
|
|
"error": "The third-party credentials could not be verified by the identity server."
|
|
}
|
|
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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The addition was successful.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"401":
|
|
description: The homeserver requires additional authentication information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/auth_response.yaml
|
|
"429":
|
|
description: This request was rate-limited.
|
|
content:
|
|
application/json:
|
|
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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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"
|
|
}
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The addition was successful.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"429":
|
|
description: This request was rate-limited.
|
|
content:
|
|
application/json:
|
|
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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The homeserver has disassociated the third-party identifier from the
|
|
user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server_unbind_result:
|
|
type: string
|
|
enum:
|
|
- 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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The identity server has disassociated the third-party identifier from the
|
|
user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server_unbind_result:
|
|
type: string
|
|
enum:
|
|
- 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
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_email_validation.yaml
|
|
required: true
|
|
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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_token_response.yaml
|
|
"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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third-party identifier already in use"
|
|
}
|
|
"403":
|
|
description: |-
|
|
The homeserver does not allow the third-party identifier as a
|
|
contact option.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third-party identifier is not allowed"
|
|
}
|
|
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
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_msisdn_validation.yaml
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: An SMS message was sent to the given phone number.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_token_response.yaml
|
|
"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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "Third-party identifier already in use"
|
|
}
|
|
"403":
|
|
description: |-
|
|
The homeserver does not allow the third-party identifier as a
|
|
contact option.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third-party identifier is not allowed"
|
|
}
|
|
tags:
|
|
- Account management
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8008
|
|
basePath:
|
|
default: /_matrix/client/v3
|
|
components:
|
|
securitySchemes:
|
|
$ref: definitions/security.yaml
|