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.
247 lines
9.4 KiB
YAML
247 lines
9.4 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
# Copyright 2022 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 Password Management API
|
|
version: 1.0.0
|
|
paths:
|
|
/account/password:
|
|
post:
|
|
summary: Changes a user's password.
|
|
description: |-
|
|
Changes the password for an account on this homeserver.
|
|
|
|
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
|
|
ensure the user changing the password is actually the owner of the
|
|
account.
|
|
|
|
An access token should be submitted to this endpoint if the client has
|
|
an active session.
|
|
|
|
The homeserver may change the flows available depending on whether a
|
|
valid access token is provided. The homeserver SHOULD NOT revoke the
|
|
access token provided in the request. Whether other access tokens for
|
|
the user are revoked depends on the request parameters.
|
|
|
|
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
|
Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
|
|
to determine if this endpoint is available.
|
|
security:
|
|
- {}
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
operationId: changePassword
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
new_password:
|
|
type: string
|
|
description: The new password for the account.
|
|
example: ihatebananas
|
|
logout_devices:
|
|
type: boolean
|
|
description: |-
|
|
Whether the user's other access tokens, and their associated devices, should be
|
|
revoked if the request succeeds. Defaults to true.
|
|
|
|
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
|
|
for the user's remaining devices.
|
|
example: true
|
|
auth:
|
|
description: Additional authentication information for the user-interactive
|
|
authentication API.
|
|
allOf:
|
|
- $ref: definitions/auth_data.yaml
|
|
required:
|
|
- new_password
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The password has been changed.
|
|
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/password/email/requestToken:
|
|
post:
|
|
summary: Requests a validation token be sent to the given email address for the
|
|
purpose of resetting a user's password
|
|
description: |-
|
|
The homeserver must check that the given email address **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
`/account/password` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the
|
|
[`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
|
|
endpoint, except that
|
|
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
|
given email address could be found. The server may instead send an
|
|
email to the given address prompting the user to create an account.
|
|
`M_THREEPID_IN_USE` may not be returned.
|
|
|
|
The homeserver should validate the email itself, either by sending a
|
|
validation email itself or by using a service it has control over.
|
|
operationId: requestTokenToResetPasswordEmail
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_email_validation.yaml
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: An email was sent to the given address.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/request_token_response.yaml
|
|
"400":
|
|
description: |-
|
|
The referenced third-party identifier is not recognised by 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_NOT_FOUND",
|
|
"error": "Email not found"
|
|
}
|
|
"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/password/msisdn/requestToken:
|
|
post:
|
|
summary: Requests a validation token be sent to the given phone number for the
|
|
purpose of resetting a user's password.
|
|
description: |-
|
|
The homeserver must check that the given phone number **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
`/account/password` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the
|
|
[`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
|
|
endpoint, except that
|
|
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
|
given phone number could be found. The server may instead send the SMS
|
|
to the given phone number prompting the user to create an account.
|
|
`M_THREEPID_IN_USE` may not be returned.
|
|
|
|
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: requestTokenToResetPasswordMSISDN
|
|
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 referenced third-party identifier is not recognised by 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_NOT_FOUND",
|
|
"error": "Phone number not found"
|
|
}
|
|
"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:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|