Merge remote-tracking branch 'matrix-org/master' into travis/releases/push-gateway/r0.1.0
Travis Ralston
6 years ago
commit
2ab2f91088
@ -0,0 +1,86 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2018 New Vector 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 Application Service API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: "/"
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/rooms/{roomAlias}":
|
||||||
|
get:
|
||||||
|
summary: Query if a room alias should exist on the application service.
|
||||||
|
description: |-
|
||||||
|
This endpoint is invoked by the homeserver on an application service to query
|
||||||
|
the existence of a given room alias. The homeserver will only query room
|
||||||
|
aliases inside the application service's ``aliases`` namespace. The
|
||||||
|
homeserver will send this request when it receives a request to join a
|
||||||
|
room alias within the application service's namespace.
|
||||||
|
operationId: queryRoomByAlias
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: roomAlias
|
||||||
|
type: string
|
||||||
|
description: The room alias being queried.
|
||||||
|
required: true
|
||||||
|
x-example: "#magicforest:example.com"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The application service indicates that this room alias exists. The
|
||||||
|
application service MUST have created a room and associated it with
|
||||||
|
the queried room alias using the client-server API. Additional
|
||||||
|
information about the room such as its name and topic can be set
|
||||||
|
before responding.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
401:
|
||||||
|
description: |-
|
||||||
|
The homeserver has not supplied credentials to the application service.
|
||||||
|
Optional error information can be included in the body of this response.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
|
403:
|
||||||
|
description: |-
|
||||||
|
The credentials supplied by the homeserver were rejected.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
The application service indicates that this room alias does not exist.
|
||||||
|
Optional error information can be included in the body of this response.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
@ -0,0 +1,83 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2018 New Vector 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 Application Service API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: "/"
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/users/{userId}":
|
||||||
|
get:
|
||||||
|
summary: Query if a user should exist on the application service.
|
||||||
|
description: |-
|
||||||
|
This endpoint is invoked by the homeserver on an application service to query
|
||||||
|
the existence of a given user ID. The homeserver will only query user IDs
|
||||||
|
inside the application service's ``users`` namespace. The homeserver will
|
||||||
|
send this request when it receives an event for an unknown user ID in
|
||||||
|
the application service's namespace, such as a room invite.
|
||||||
|
operationId: queryUserById
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: userId
|
||||||
|
type: string
|
||||||
|
description: The user ID being queried.
|
||||||
|
required: true
|
||||||
|
x-example: "@alice:example.com"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The application service indicates that this user exists. The application
|
||||||
|
service MUST create the user using the client-server API.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
401:
|
||||||
|
description: |-
|
||||||
|
The homeserver has not supplied credentials to the application service.
|
||||||
|
Optional error information can be included in the body of this response.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
|
403:
|
||||||
|
description: |-
|
||||||
|
The credentials supplied by the homeserver were rejected.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
The application service indicates that this user does not exist.
|
||||||
|
Optional error information can be included in the body of this response.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
@ -0,0 +1,74 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2018 New Vector 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 Application Service API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: "/"
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/transactions/{txnId}":
|
||||||
|
put:
|
||||||
|
summary: Send some events to the application service.
|
||||||
|
description: |-
|
||||||
|
This API is called by the homeserver when it wants to push an event
|
||||||
|
(or batch of events) to the application service.
|
||||||
|
|
||||||
|
Note that the application service should distinguish state events
|
||||||
|
from message events via the presence of a ``state_key``, rather than
|
||||||
|
via the event type.
|
||||||
|
operationId: sendTransaction
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: txnId
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The transaction ID for this set of events. Homeservers generate
|
||||||
|
these IDs and they are used to ensure idempotency of requests.
|
||||||
|
required: true
|
||||||
|
x-example: "35"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
description: A list of events.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"events": [
|
||||||
|
{"$ref": "../../event-schemas/examples/m.room.member"},
|
||||||
|
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
description: Transaction information
|
||||||
|
properties:
|
||||||
|
events:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
A list of events, formatted as per the Client-Server API.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: Event
|
||||||
|
required: ["events"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The transaction was processed successfully.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
# Copyright 2018 New Vector 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 Application Service Room Directory API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
# Note: this is the same access_token definition used elsewhere in the client
|
||||||
|
# server API, however this expects an access token for an application service.
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/directory/list/appservice/{networkId}/{roomId}":
|
||||||
|
put:
|
||||||
|
summary: |-
|
||||||
|
Updates a room's visibility in the application service's room directory.
|
||||||
|
description: |-
|
||||||
|
Updates the visibility of a given room on the application service's room
|
||||||
|
directory.
|
||||||
|
|
||||||
|
This API is similar to the room directory visibility API used by clients
|
||||||
|
to update the homeserver's more general room directory.
|
||||||
|
|
||||||
|
This API requires the use of an application service access token (``as_token``)
|
||||||
|
instead of a typical client's access_token. This API cannot be invoked by
|
||||||
|
users who are not identified as application services.
|
||||||
|
operationId: updateAppserviceRoomDirectoryVsibility
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: networkId
|
||||||
|
description: |-
|
||||||
|
The protocol (network) ID to update the room list for. This would
|
||||||
|
have been provided by the application service as being listed as
|
||||||
|
a supported protocol.
|
||||||
|
required: true
|
||||||
|
x-example: "irc"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room ID to add to the directory.
|
||||||
|
required: true
|
||||||
|
x-example: "!somewhere:domain.com"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
visibility:
|
||||||
|
type: string
|
||||||
|
enum: ["public", "private"]
|
||||||
|
description: |-
|
||||||
|
Whether the room should be visible (public) in the directory
|
||||||
|
or not (private).
|
||||||
|
example: "public"
|
||||||
|
required: ['visibility']
|
||||||
|
security:
|
||||||
|
# again, this is the appservice's token - not a typical client's
|
||||||
|
- accessToken: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The room's directory visibility has been updated.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
tags:
|
||||||
|
- Application service room directory management
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
title: Homeserver Information
|
||||||
|
description: |-
|
||||||
|
Used by clients to discover homeserver information.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
base_url:
|
||||||
|
type: string
|
||||||
|
description: The base URL for the homeserver for client-server connections.
|
||||||
|
example: https://matrix.example.com
|
||||||
|
required:
|
||||||
|
- base_url
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
title: Identity Server Information
|
||||||
|
description: |-
|
||||||
|
Used by clients to discover identity server information.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
base_url:
|
||||||
|
type: string
|
||||||
|
description: The base URL for the identity server for client-server connections.
|
||||||
|
example: https://identity.example.com
|
||||||
|
required:
|
||||||
|
- base_url
|
||||||
@ -0,0 +1,103 @@
|
|||||||
|
# Copyright 2018 New Vector 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 OpenID 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:
|
||||||
|
"/user/{userId}/openid/request_token":
|
||||||
|
post:
|
||||||
|
summary: Get an OpenID token object to verify the requester's identity.
|
||||||
|
description: |-
|
||||||
|
Gets an OpenID token object that the requester may supply to another
|
||||||
|
service to verify their identity in Matrix. The generated token is only
|
||||||
|
valid for exchanging for user information from the federation API for
|
||||||
|
OpenID.
|
||||||
|
|
||||||
|
The access token generated is only valid for the OpenID API. It cannot
|
||||||
|
be used to request another OpenID access token or call ``/sync``, for
|
||||||
|
example.
|
||||||
|
operationId: requestOpenIdToken
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: userId
|
||||||
|
description: |-
|
||||||
|
The user to request and OpenID token for. Should be the user who
|
||||||
|
is authenticated for the request.
|
||||||
|
required: true
|
||||||
|
x-example: "@alice:example.com"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
description: An empty object. Reserved for future expansion.
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {}
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
OpenID token information. This response is nearly compatible with the
|
||||||
|
response documented in the `OpenID 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
|
||||||
|
with the only difference being the lack of an ``id_token``. Instead,
|
||||||
|
the Matrix homeserver's name is provided.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"access_token": "SomeT0kenHere",
|
||||||
|
"token_type": "Bearer",
|
||||||
|
"matrix_server_name": "example.com",
|
||||||
|
"expires_in": 3600,
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
access_token:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An access token the consumer may use to verify the identity of
|
||||||
|
the person who generated the token. This is given to the federation
|
||||||
|
API ``GET /openid/userinfo``.
|
||||||
|
token_type:
|
||||||
|
type: string
|
||||||
|
description: The string ``Bearer``.
|
||||||
|
matrix_server_name:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The homeserver domain the consumer should use when attempting to
|
||||||
|
verify the user's identity.
|
||||||
|
expires_in:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
The number of seconds before this token expires and a new one must
|
||||||
|
be generated.
|
||||||
|
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- OpenID
|
||||||
@ -0,0 +1,66 @@
|
|||||||
|
# Copyright 2018 New Vector 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 Server Discovery API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /.well-known
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/matrix/client":
|
||||||
|
get:
|
||||||
|
summary: Gets Matrix server discovery information about the domain.
|
||||||
|
description: |-
|
||||||
|
Gets discovery information about the domain. The file may include
|
||||||
|
additional keys, which MUST follow the Java package naming convention,
|
||||||
|
e.g. ``com.example.myapp.property``. This ensures property names are
|
||||||
|
suitably namespaced for each application and reduces the risk of
|
||||||
|
clashes.
|
||||||
|
|
||||||
|
Note that this endpoint is not necessarily handled by the homeserver,
|
||||||
|
but by another webserver, to be used for discovering the homeserver URL.
|
||||||
|
operationId: getWellknown
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Server discovery information.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"m.homeserver": {
|
||||||
|
"base_url": "https://matrix.example.com"
|
||||||
|
},
|
||||||
|
"m.identity_server": {
|
||||||
|
"base_url": "https://identity.example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
m.homeserver:
|
||||||
|
description: Information about the homeserver to connect to.
|
||||||
|
"$ref": "definitions/wellknown/homeserver.yaml"
|
||||||
|
m.identity_server:
|
||||||
|
description: Optional. Information about the identity server to connect to.
|
||||||
|
"$ref": "definitions/wellknown/identity_server.yaml"
|
||||||
|
additionalProperties:
|
||||||
|
description: Application-dependent keys using Java package naming convention.
|
||||||
|
required:
|
||||||
|
- m.homeserver
|
||||||
|
404:
|
||||||
|
description: No server discovery information available.
|
||||||
|
tags:
|
||||||
|
- Server administration
|
||||||
@ -0,0 +1,212 @@
|
|||||||
|
# Copyright 2018 New Vector 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 Identity Service Phone Number Associations API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/identity/api/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/validate/msisdn/requestToken":
|
||||||
|
post:
|
||||||
|
summary: Request a token for validating a phone number.
|
||||||
|
description: |-
|
||||||
|
Create a session for validating a phone number.
|
||||||
|
|
||||||
|
The identity service will send an SMS message containing a token. If
|
||||||
|
that token is presented to the identity service in the future, it
|
||||||
|
indicates that that user was able to read the SMS for that phone
|
||||||
|
number, and so we validate ownership of the phone number.
|
||||||
|
|
||||||
|
Note that Home Servers offer APIs that proxy this API, adding
|
||||||
|
additional behaviour on top, for example,
|
||||||
|
``/register/msisdn/requestToken`` is designed specifically for use when
|
||||||
|
registering an account and therefore will inform the user if the phone
|
||||||
|
number given is already registered on the server.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with older versions of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: msisdnRequestToken
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"country": "GB",
|
||||||
|
"phone_number": "07700900001",
|
||||||
|
"send_attempt": 1
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: A unique string used to identify the validation attempt.
|
||||||
|
country:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The two-letter uppercase ISO country code that the number in
|
||||||
|
``phone_number`` should be parsed as if it were dialled from.
|
||||||
|
phone_number:
|
||||||
|
type: string
|
||||||
|
description: The phone number to validate.
|
||||||
|
send_attempt:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
Optional. If specified, the server will only send an SMS if
|
||||||
|
the ``send_attempt`` is a number greater than the most recent
|
||||||
|
one which it has seen (or if it has never seen one), scoped
|
||||||
|
to that ``country`` + ``phone_number`` + ``client_secret``
|
||||||
|
triple. This is to avoid repeatedly sending the same SMS in
|
||||||
|
the case of request retries between the POSTing user and the
|
||||||
|
identity service. The client should increment this value if
|
||||||
|
they desire a new SMS (e.g. a reminder) to be sent.
|
||||||
|
next_link:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
Optional. When the validation is completed, the identity
|
||||||
|
service will redirect the user to this URL.
|
||||||
|
required: ["client_secret", "country", "phone_number"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
Session created.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"sid": "1234"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The session ID.
|
||||||
|
required: ['sid']
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error ocurred. Some possible errors are:
|
||||||
|
|
||||||
|
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
|
||||||
|
- ``M_SEND_ERROR``: The validation SMS could not be sent.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_INVALID_ADDRESS",
|
||||||
|
"error": "The phone number is not valid"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/validate/msisdn/submitToken":
|
||||||
|
post:
|
||||||
|
summary: Validate ownership of a phone number.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of a phone number.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the phone number is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the phone number address with any Matrix user
|
||||||
|
ID. Specifically, calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with older versions of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: msisdnSubmitTokenPost
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"token": "atoken"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token generated by the ``requestToken`` call and sent to the user.
|
||||||
|
required: ["sid", "client_secret", "token"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The success of the validation.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the validation was successful or not.
|
||||||
|
required: ['success']
|
||||||
|
get:
|
||||||
|
summary: Validate ownership of a phone number.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of a phone number.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the phone number address is
|
||||||
|
considered to have been validated. This does not publish any
|
||||||
|
information publicly, or associate the phone number with any Matrix
|
||||||
|
user ID. Specifically, calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
Note that, in contrast with the POST version, this endpoint will be
|
||||||
|
used by end-users, and so the response should be human-readable.
|
||||||
|
operationId: msisdnSubmitTokenGet
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: sid
|
||||||
|
required: true
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
x-example: 1234
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: client_secret
|
||||||
|
required: true
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
x-example: monkeys_are_GREAT
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: token
|
||||||
|
required: true
|
||||||
|
description: The token generated by the ``requestToken`` call and sent to the user.
|
||||||
|
x-example: atoken
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: Phone number is validated.
|
||||||
|
"3xx":
|
||||||
|
description: |-
|
||||||
|
Phone number address is validated, and the ``next_link`` parameter
|
||||||
|
was provided to the ``requestToken`` call. The user must be
|
||||||
|
redirected to the URL provided by the ``next_link`` parameter.
|
||||||
|
"4xx":
|
||||||
|
description:
|
||||||
|
Validation failed.
|
||||||
@ -0,0 +1,71 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: m.presence
|
||||||
|
description: |-
|
||||||
|
An EDU representing presence updates for users of the sending homeserver.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: enum
|
||||||
|
enum: ['m.presence']
|
||||||
|
description: The string ``m.presence``
|
||||||
|
example: "m.presence"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: The presence updates and requests.
|
||||||
|
title: Presence Update
|
||||||
|
properties:
|
||||||
|
push:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
A list of presence updates that the receiving server is likely
|
||||||
|
to be interested in.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: User Presence Update
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: The user ID this presence EDU is for.
|
||||||
|
example: "@john:matrix.org"
|
||||||
|
presence:
|
||||||
|
type: enum
|
||||||
|
enum: ['offline', 'unavailable', 'online']
|
||||||
|
description: The presence of the user.
|
||||||
|
example: "online"
|
||||||
|
status_msg:
|
||||||
|
type: string
|
||||||
|
description: An optional description to accompany the presence.
|
||||||
|
example: "Making cupcakes"
|
||||||
|
last_active_ago:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: |-
|
||||||
|
The number of milliseconds that have elapsed since the user
|
||||||
|
last did something.
|
||||||
|
example: 5000
|
||||||
|
currently_active:
|
||||||
|
type: boolean
|
||||||
|
description: |-
|
||||||
|
True if the user is likely to be interacting with their
|
||||||
|
client. This may be indicated by the user having a
|
||||||
|
``last_active_ago`` within the last few minutes. Defaults
|
||||||
|
to false.
|
||||||
|
example: true
|
||||||
|
required: ['user_id', 'presence', 'last_active_ago']
|
||||||
|
required: ['push']
|
||||||
@ -0,0 +1,46 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: m.presence_accept
|
||||||
|
description: |-
|
||||||
|
An EDU representing approval for the observing user to subscribe to the
|
||||||
|
presence of the the observed user.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: enum
|
||||||
|
enum: ['m.presence_accept']
|
||||||
|
description: The string ``m.presence_accept``
|
||||||
|
example: "m.presence_accept"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: The invite information.
|
||||||
|
title: Invite Information
|
||||||
|
properties:
|
||||||
|
observed_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that has approved the ``observer_user`` to
|
||||||
|
subscribe to their presence.
|
||||||
|
example: "@alice:elsewhere.com"
|
||||||
|
observer_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that requested to subscribe to the presence of
|
||||||
|
the ``observed_user``.
|
||||||
|
example: "@john:matrix.org"
|
||||||
|
required: ['observer_user', 'observed_user']
|
||||||
@ -0,0 +1,55 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: m.presence_deny
|
||||||
|
description: |-
|
||||||
|
An EDU representing a declination or revocation for the observing user
|
||||||
|
to subscribe to the presence of the observed user.
|
||||||
|
example: {
|
||||||
|
"origin": "domain.com",
|
||||||
|
"destination": "elsewhere.org",
|
||||||
|
"edu_type": "m.presence_deny",
|
||||||
|
"content": {
|
||||||
|
"observed_user": "@alice:elsewhere.org",
|
||||||
|
"observer_user": "@john:domain.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: enum
|
||||||
|
enum: ['m.presence_deny']
|
||||||
|
description: The string ``m.presence_deny``
|
||||||
|
example: "m.presence_deny"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: The invite information.
|
||||||
|
title: Invite Information
|
||||||
|
properties:
|
||||||
|
observed_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that has declined or revoked the ``observer_user`` from
|
||||||
|
subscribing to their presence.
|
||||||
|
example: "@alice:elsewhere.com"
|
||||||
|
observer_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that requested to subscribe to the presence of
|
||||||
|
the ``observed_user``.
|
||||||
|
example: "@john:matrix.org"
|
||||||
|
required: ['observer_user', 'observed_user']
|
||||||
@ -0,0 +1,45 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: m.presence_invite
|
||||||
|
description: |-
|
||||||
|
An EDU representing a request to subscribe to a user's presence.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: enum
|
||||||
|
enum: ['m.presence_invite']
|
||||||
|
description: The string ``m.presence_invite``
|
||||||
|
example: "m.presence_invite"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: The invite information.
|
||||||
|
title: Invite Information
|
||||||
|
properties:
|
||||||
|
observed_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID the ``observer_user`` would like to subscribe
|
||||||
|
to the presence of.
|
||||||
|
example: "@alice:elsewhere.com"
|
||||||
|
observer_user:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that is wishing to subscribe to the presence of
|
||||||
|
the ``observed_user``.
|
||||||
|
example: "@john:matrix.org"
|
||||||
|
required: ['observer_user', 'observed_user']
|
||||||
@ -0,0 +1,82 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: m.receipt
|
||||||
|
description: |-
|
||||||
|
An EDU representing receipt updates for users of the sending homeserver.
|
||||||
|
When receiving receipts, the server should only update entries that are
|
||||||
|
listed in the EDU. Receipts previously received that do not appear in the
|
||||||
|
EDU should not be removed or otherwise manipulated.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: enum
|
||||||
|
enum: ['m.receipt']
|
||||||
|
description: The string ``m.receipt``
|
||||||
|
example: "m.receipt"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
Receipts for a particular room. The string key is the room ID for
|
||||||
|
which the receipts under it belong.
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: Room Receipts
|
||||||
|
properties:
|
||||||
|
# We strongly define the receipt type to help spec future ones later
|
||||||
|
# on. At that point, m.read can become optional (maybe).
|
||||||
|
"m.read":
|
||||||
|
type: object
|
||||||
|
description: Read receipts for users in the room.
|
||||||
|
title: User Read Receipt
|
||||||
|
properties:
|
||||||
|
event_ids:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The extremity event IDs that the user has read up to.
|
||||||
|
minItems: 1
|
||||||
|
maxItems: 1
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: ['$read_this_event:matrix.org']
|
||||||
|
data:
|
||||||
|
type: object
|
||||||
|
description: Metadata for the read receipt.
|
||||||
|
title: Read Receipt Metadata
|
||||||
|
properties:
|
||||||
|
ts:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: |-
|
||||||
|
A POSIX timestamp in milliseconds for when the user read
|
||||||
|
the event specified in the read receipt.
|
||||||
|
example: 1533358089009
|
||||||
|
required: ['ts']
|
||||||
|
required: ['event_ids', 'data']
|
||||||
|
required: ['m.read']
|
||||||
|
example: {
|
||||||
|
"!some_room:domain.com": {
|
||||||
|
"m.read": {
|
||||||
|
"@john:matrix.org": {
|
||||||
|
"event_ids": ["$read_this_event:matrix.org"],
|
||||||
|
"data": {
|
||||||
|
"ts": 1533358089009
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@ -0,0 +1,19 @@
|
|||||||
|
# Copyright 2018 New Vector 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.
|
||||||
|
signedRequest:
|
||||||
|
type: apiKey
|
||||||
|
description: |-
|
||||||
|
The ``Authorization`` header defined in the `Authentication`_ section.
|
||||||
|
name: Authorization
|
||||||
|
in: header
|
||||||
@ -0,0 +1,63 @@
|
|||||||
|
# Copyright 2017 Kamax.io
|
||||||
|
# Copyright 2018 New Vector 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 Federation OpenID API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8448
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/federation/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/openid/userinfo":
|
||||||
|
get:
|
||||||
|
summary: Exchange an OpenID token for user information
|
||||||
|
description: |-
|
||||||
|
Exchanges an OpenID access token for information about the user
|
||||||
|
who generated the token. Currently this only exposes the Matrix
|
||||||
|
User ID of the owner.
|
||||||
|
operationId: exchangeOpenIdToken
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: access_token
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The OpenID access token to get information about the owner for.
|
||||||
|
required: true
|
||||||
|
x-example: SomeT0kenHere
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
Information about the user who generated the OpenID access token.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
sub:
|
||||||
|
type: string
|
||||||
|
description: The Matrix User ID who generated the token.
|
||||||
|
example: "@alice:example.com"
|
||||||
|
required: ['sub']
|
||||||
|
401:
|
||||||
|
description: The token was not recognized or has expired.
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_UNKNOWN_TOKEN",
|
||||||
|
"error": "Access token unknown or expired"
|
||||||
|
}
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Specify how to control the power level required for ``@room``
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify ``changed`` field behaviour in device tracking process
|
||||||
@ -0,0 +1,7 @@
|
|||||||
|
End-to-end encryption for group chats:
|
||||||
|
|
||||||
|
- Olm and Megolm messaging algorithms.
|
||||||
|
- ``m.room.encrypted``, ``m.room.encryption``, ``m.room_key`` events.
|
||||||
|
- Device verification process.
|
||||||
|
- ``device_one_time_keys_count`` sync parameter.
|
||||||
|
- ``device_lists:left`` sync parameter.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add ``.well-known`` server discovery method
|
||||||
@ -0,0 +1 @@
|
|||||||
|
``POST /account/3pid/msisdn/requestToken``, ``POST /register/msisdn/requestToken``, and ``POST /account/password/msisdn/requestToken``
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add support for Room Versions.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify how access tokens are meant to be supplied to the homeserver.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Document additional parameters on the ``/createRoom`` API.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Guests can now call /context and /event to fetch events
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add a common standard for user, room, and group mentions in messages.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add server ACLs as an option for controlling federation in a room.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add new push rules for encrypted events and ``@room`` notifications.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add third party network room directories, as provided by application services.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the supported HTML features for room messages.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the object structures and defaults for Filters.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify that left rooms also have account data in ``/sync``.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Fix naming of the body field in ``PUT /directory/room``.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the filter object schema used in room searching.
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"algorithm": "m.megolm.v1.aes-sha2",
|
||||||
|
"ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...",
|
||||||
|
"device_id": "RJYKSTBOIE",
|
||||||
|
"sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA",
|
||||||
|
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
|
||||||
|
},
|
||||||
|
"event_id": "$WLGTSEFSEF:localhost",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"origin_server_ts": 1476648761524,
|
||||||
|
"sender": "@example:localhost",
|
||||||
|
"type": "m.room.encrypted"
|
||||||
|
}
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"type": "m.room.encrypted",
|
||||||
|
"sender": "@example:localhost",
|
||||||
|
"content": {
|
||||||
|
"algorithm": "m.olm.v1.curve25519-aes-sha2",
|
||||||
|
"sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU",
|
||||||
|
"ciphertext": {
|
||||||
|
"7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": {
|
||||||
|
"type": 0,
|
||||||
|
"body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@ -0,0 +1,13 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"algorithm": "m.megolm.v1.aes-sha2",
|
||||||
|
"rotation_period_ms": 604800000,
|
||||||
|
"rotation_period_msgs": 100
|
||||||
|
},
|
||||||
|
"event_id": "$WLGTSEFJJKJ:localhost",
|
||||||
|
"origin_server_ts": 1476648761524,
|
||||||
|
"sender": "@example:localhost",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"state_key": "",
|
||||||
|
"type": "m.room.encryption"
|
||||||
|
}
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"age": 242352,
|
||||||
|
"content": {
|
||||||
|
"allow_ip_literals": false,
|
||||||
|
"allow": ["*"],
|
||||||
|
"deny": ["*.evil.com", "evil.com"]
|
||||||
|
},
|
||||||
|
"state_key": "",
|
||||||
|
"origin_server_ts": 1431961217939,
|
||||||
|
"event_id": "$WLGTSEFSEF:localhost",
|
||||||
|
"type": "m.room.server_acl",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"sender": "@example:localhost"
|
||||||
|
}
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"algorithm": "m.megolm.v1.aes-sha2",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
|
||||||
|
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
|
||||||
|
},
|
||||||
|
"type": "m.room_key"
|
||||||
|
}
|
||||||
@ -0,0 +1,61 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/event.yaml
|
||||||
|
|
||||||
|
description: |-
|
||||||
|
This event type is used when sending encrypted events. It can be used either
|
||||||
|
within a room (in which case it will have all of the `Room Event fields`_), or
|
||||||
|
as a `to-device`_ event.
|
||||||
|
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- m.olm.v1.curve25519-aes-sha2
|
||||||
|
- m.megolm.v1.aes-sha2
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm used to encrypt this event. The
|
||||||
|
value of this field determines which other properties will be
|
||||||
|
present.
|
||||||
|
ciphertext:
|
||||||
|
oneOf:
|
||||||
|
- type: string
|
||||||
|
- type: object
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: CiphertextInfo
|
||||||
|
properties:
|
||||||
|
body:
|
||||||
|
type: string
|
||||||
|
description: The encrypted payload.
|
||||||
|
type:
|
||||||
|
type: integer
|
||||||
|
description: The Olm message type.
|
||||||
|
description: |-
|
||||||
|
The encrypted content of the event. Either the encrypted payload
|
||||||
|
itself, in the case of a Megolm event, or a map from the recipient
|
||||||
|
Curve25519 identity key to ciphertext information, in the case of an
|
||||||
|
Olm event. For more details, see `Messaging Algorithms`_.
|
||||||
|
sender_key:
|
||||||
|
type: string
|
||||||
|
description: The Curve25519 key of the sender.
|
||||||
|
device_id:
|
||||||
|
type: string
|
||||||
|
description: The ID of the sending device. Required with Megolm.
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The ID of the session used to encrypt the message. Required with
|
||||||
|
Megolm.
|
||||||
|
required:
|
||||||
|
- algorithm
|
||||||
|
- sender_key
|
||||||
|
- ciphertext
|
||||||
|
type: object
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.room.encrypted
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/state_event.yaml
|
||||||
|
description: Defines how messages sent in this room should be encrypted.
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- "m.megolm.v1.aes-sha2"
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm to be used to encrypt messages sent in this
|
||||||
|
room.
|
||||||
|
rotation_period_ms:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
How long the session should be used before changing it. ``604800000``
|
||||||
|
(a week) is the recommended default.
|
||||||
|
rotation_period_msgs:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
How many messages should be sent before changing the session. ``100`` is the
|
||||||
|
recommended default.
|
||||||
|
required:
|
||||||
|
- algorithm
|
||||||
|
type: object
|
||||||
|
state_key:
|
||||||
|
description: A zero-length string.
|
||||||
|
pattern: '^$'
|
||||||
|
type: string
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.room.encryption
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Server ACL
|
||||||
|
description: |-
|
||||||
|
An event to indicate which servers are permitted to participate in the
|
||||||
|
room. Server ACLs may allow or deny groups of hosts. All servers participating
|
||||||
|
in the room, including those that are denied, are expected to uphold the
|
||||||
|
server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
|
||||||
|
list in order for the ACLs to remain effective.
|
||||||
|
|
||||||
|
The ``allow`` and ``deny`` lists are lists of globs supporting ``?`` and ``*``
|
||||||
|
as wildcards. When comparing against the server ACLs, the suspect server's port
|
||||||
|
number must not be considered. Therefore ``evil.com``, ``evil.com:8448``, and
|
||||||
|
``evil.com:1234`` would all match rules that apply to ``evil.com``, for example.
|
||||||
|
|
||||||
|
The ACLs are applied to servers when they make requests, and are applied in
|
||||||
|
the following order:
|
||||||
|
|
||||||
|
1. If there is no ``m.room.server_acl`` event in the room state, allow.
|
||||||
|
#. If the server name is an IP address (v4 or v6) literal, and ``allow_ip_literals``
|
||||||
|
is present and ``false``, deny.
|
||||||
|
#. If the server name matches an entry in the ``deny`` list, deny.
|
||||||
|
#. If the server name matches an entry in the ``allow`` list, allow.
|
||||||
|
#. Otherwise, deny.
|
||||||
|
|
||||||
|
.. Note::
|
||||||
|
Server ACLs do not restrict the events relative to the room DAG via authorisation
|
||||||
|
rules, but instead act purely at the network layer to determine which servers are
|
||||||
|
allowed to connect and interact with a given room.
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
Failing to provide an ``allow`` rule of some kind will prevent **all**
|
||||||
|
servers from participating in the room, including the sender. This renders
|
||||||
|
the room unusable. A common allow rule is ``[ "*" ]`` which would still
|
||||||
|
permit the use of the ``deny`` list without losing the room.
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
All compliant servers must implement server ACLs. However, legacy or noncompliant
|
||||||
|
servers exist which do not uphold ACLs, and these MUST be manually appended to
|
||||||
|
the denied hosts list when setting an ACL to prevent them from leaking events from
|
||||||
|
banned servers into a room. Currently, the only way to determine noncompliant hosts is
|
||||||
|
to check the ``prev_events`` of leaked events, therefore detecting servers which
|
||||||
|
are not upholding the ACLs. Server versions can also be used to try to detect hosts that
|
||||||
|
will not uphold the ACLs, although this is not comprehensive. Server ACLs were added
|
||||||
|
in Synapse v0.32.0, although other server implementations and versions exist in the world.
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/state_event.yaml
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
allow_ip_literals:
|
||||||
|
type: boolean
|
||||||
|
description: |-
|
||||||
|
True to allow server names that are IP address literals. False to
|
||||||
|
deny. Defaults to true if missing or otherwise not a boolean.
|
||||||
|
|
||||||
|
This is strongly recommended to be set to ``false`` as servers running
|
||||||
|
with IP literal names are strongly discouraged in order to require
|
||||||
|
legitimate homeservers to be backed by a valid registered domain name.
|
||||||
|
allow:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The server names to allow in the room, excluding any port information.
|
||||||
|
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||||
|
matches zero or more characters and ``?`` matches exactly one character.
|
||||||
|
|
||||||
|
**This defaults to an empty list when not provided, effectively disallowing
|
||||||
|
every server.**
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
deny:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The server names to disallow in the room, excluding any port information.
|
||||||
|
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||||
|
matches zero or more characters and ``?`` matches exactly one character.
|
||||||
|
|
||||||
|
This defaults to an empty list when not provided.
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
|
state_key:
|
||||||
|
description: A zero-length string.
|
||||||
|
pattern: '^$'
|
||||||
|
type: string
|
||||||
|
type:
|
||||||
|
enum: ['m.room.server_acl']
|
||||||
|
type: string
|
||||||
@ -0,0 +1,35 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/event.yaml
|
||||||
|
|
||||||
|
description: |-
|
||||||
|
This event type is used to exchange keys for end-to-end encryption. Typically
|
||||||
|
it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event.
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
enum: ["m.megolm.v1.aes-sha2"]
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm the key in this event is to be used with.
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: The room where the key is used.
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
description: The ID of the session that the key is for.
|
||||||
|
session_key:
|
||||||
|
type: string
|
||||||
|
description: The key to be exchanged.
|
||||||
|
required:
|
||||||
|
- algorithm
|
||||||
|
- room_id
|
||||||
|
- session_id
|
||||||
|
- session_key
|
||||||
|
type: object
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.room_key
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue