mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-01-21 14:53:42 +01:00
62910a28cc
* master: Update example Fix 404s in links from room v1 spec Provide a more complete example of a "minimally-sized event" Revert signature change for redactable event test Clarify how many PDUs are in a given transaction object Clarify that the server shouldn't process retries for UIA Clarify when authorization and rate-limiting are not applicable Skip over partial event definitions in examples Rename example to invite_room_state Shorten references to StrippedState in s2s spec Fix examples of StrippedState in s2s spec Clarify exactly what StrippedState is Clarify that UIA stages cannot be attempted twice Fix test vectors with invalid JSON and signature Spec 3PID unbind API Spec MSISDN UIA support
399 lines
16 KiB
YAML
399 lines
16 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.
|
|
|
|
``submit_url`` is an optional field containing a URL where the
|
|
client must submit a validation token to, with identical parameters
|
|
to the Identity Service API's ``/validate/email/submitToken``
|
|
endpoint. The homeserver will send this token to the user, which
|
|
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.
|
|
examples:
|
|
application/json: {
|
|
"submit_url": "https://example.org/path/to/submitToken"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional URL to submit information to to verify a
|
|
third-party identifier.
|
|
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:
|
|
- 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:
|
|
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
|
|
indentity 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:
|
|
- User data
|
|
"/account/3pid/email/requestToken":
|
|
post:
|
|
summary: Begins the validation process for an email address for association with the user's account.
|
|
description: |-
|
|
The homeserver should 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|_ endpoint. The homeserver has the
|
|
choice of validating the email address itself, or proxying the request
|
|
to the ``validate/email/requestToken`` Identity Server API on the
|
|
server sent in ``id_server``.
|
|
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.
|
|
Note that this may be an email containing the validation token or
|
|
it may be informing the user of an error.
|
|
|
|
``submit_url`` is an optional field containing a URL where the
|
|
client must submit a validation token to, with identical parameters
|
|
to the Identity Service API's ``/validate/email/submitToken``
|
|
endpoint. The homeserver will send this token to the user, which
|
|
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.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client
|
|
must submit a validation token to, with identical
|
|
parameters to the Identity Service API's
|
|
``/validate/email/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which 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.
|
|
example: "https://example.org/path/to/submitToken"
|
|
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: |-
|
|
The homeserver should 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|_ endpoint. The homeserver has the
|
|
choice of validating the phone number itself, or proxying the request
|
|
to the ``validate/msisdn/requestToken`` Identity Server API on the
|
|
server sent in ``id_server``.
|
|
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.
|
|
|
|
``submit_url`` is an optional field containing a URL where the
|
|
client must submit a validation token to, with identical parameters
|
|
to the Identity Service API's ``/validate/msisdn/submitToken``
|
|
endpoint. The homeserver will send this token to the user, which
|
|
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.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client
|
|
must submit a validation token to, with identical
|
|
parameters to the Identity Service API's
|
|
``/validate/email/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which 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.
|
|
example: "https://example.org/path/to/submitToken"
|
|
|
|
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"
|
|
}
|