Merge remote-tracking branch 'matrix-org/master' into travis/s2s/presence
Travis Ralston
6 years ago
commit
a53fa9300d
@ -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: User identifier
|
||||||
|
description: |-
|
||||||
|
Identification information for a user
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
type:
|
||||||
|
type: string
|
||||||
|
description: The type of identification. See `Identifier types`_ for supported values and additional property descriptions.
|
||||||
|
required:
|
||||||
|
- type
|
||||||
|
additionalProperties: true
|
||||||
@ -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: int
|
||||||
|
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,179 @@
|
|||||||
|
# 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 Establishing Associations API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/identity/api/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/3pid/getValidated3pid":
|
||||||
|
get:
|
||||||
|
summary: Check whether ownership of a 3pid was validated.
|
||||||
|
description: A client can check whether ownership of a 3pid was validated
|
||||||
|
operationId: getValidated3pid
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: sid
|
||||||
|
description: The Session ID generated by the ``requestToken`` call.
|
||||||
|
required: true
|
||||||
|
x-example: 1234
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: client_secret
|
||||||
|
description: The client secret passed to the ``requestToken`` call.
|
||||||
|
required: true
|
||||||
|
x-example: monkeys_are_GREAT
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Validation information for the session.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"medium": "email",
|
||||||
|
"validated_at": 1457622739026,
|
||||||
|
"address": "louise@bobs.burgers"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The medium type of the 3pid.
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The address of the 3pid being looked up.
|
||||||
|
validated_at:
|
||||||
|
type: integer
|
||||||
|
description: Timestamp indicating the time that the 3pid was validated.
|
||||||
|
400:
|
||||||
|
description: |-
|
||||||
|
The session has not been validated.
|
||||||
|
|
||||||
|
If the session has not been validated, then ``errcode`` will be
|
||||||
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
||||||
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
||||||
|
"error": "This validation session has not yet been completed"
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: The Session ID or client secret were not found
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NO_VALID_SESSION",
|
||||||
|
"error": "No valid session was found matching that sid and client secret"
|
||||||
|
}
|
||||||
|
"/bind":
|
||||||
|
post:
|
||||||
|
summary: Publish an association between a session and a Matrix user ID.
|
||||||
|
description: |-
|
||||||
|
Publish an association between a session and a Matrix user ID.
|
||||||
|
|
||||||
|
Future calls to ``/lookup`` for any of the session\'s 3pids will return
|
||||||
|
this association.
|
||||||
|
|
||||||
|
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: bind
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"mxid": "@ears:matrix.org"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The Session ID generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret passed to the ``requestToken`` call.
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID to associate with the 3pids.
|
||||||
|
required: ["sid", "client_secret", "mxid"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The association was published.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"address": "louise@bobs.burgers",
|
||||||
|
"medium": "email",
|
||||||
|
"mxid": "@ears:matrix.org",
|
||||||
|
"not_before": 1428825849161,
|
||||||
|
"not_after": 4582425849161,
|
||||||
|
"ts": 1428825849161,
|
||||||
|
|
||||||
|
"signatures": {
|
||||||
|
"matrix.org": {
|
||||||
|
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The 3pid address of the user being looked up.
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The medium type of the 3pid.
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID associated with the 3pid.
|
||||||
|
not_before:
|
||||||
|
type: integer
|
||||||
|
description: A unix timestamp before which the association is not known to be valid.
|
||||||
|
not_after:
|
||||||
|
type: integer
|
||||||
|
description: A unix timestamp after which the association is not known to be valid.
|
||||||
|
ts:
|
||||||
|
type: integer
|
||||||
|
description: The unix timestamp at which the association was verified.
|
||||||
|
signatures:
|
||||||
|
type: object
|
||||||
|
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
|
||||||
|
400:
|
||||||
|
description: |-
|
||||||
|
The association was not published.
|
||||||
|
|
||||||
|
If the session has not been validated, then ``errcode`` will be
|
||||||
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
||||||
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
||||||
|
"error": "This validation session has not yet been completed"
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: The Session ID or client secret were not found
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NO_VALID_SESSION",
|
||||||
|
"error": "No valid session was found matching that sid and client secret"
|
||||||
|
}
|
||||||
@ -0,0 +1,197 @@
|
|||||||
|
# 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 Email Associations API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/identity/api/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/validate/email/requestToken":
|
||||||
|
post:
|
||||||
|
summary: Request a token for validating an email address.
|
||||||
|
description: |-
|
||||||
|
Create a session for validating an email address.
|
||||||
|
|
||||||
|
The identity service will send an email 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 email for that email address, and
|
||||||
|
so we validate ownership of the email address.
|
||||||
|
|
||||||
|
Note that Home Servers offer APIs that proxy this API, adding
|
||||||
|
additional behaviour on top, for example,
|
||||||
|
``/register/email/requestToken`` is designed specifically for use when
|
||||||
|
registering an account and therefore will inform the user if the email
|
||||||
|
address 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: emailRequestToken
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"email": "foo@example.com",
|
||||||
|
"send_attempt": 1
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: A unique string used to identify the validation attempt
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
description: The email address to validate.
|
||||||
|
send_attempt:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
Optional. If specified, the server will only send an email 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 ``email`` + ``client_secret`` pair. This is to avoid
|
||||||
|
repeatedly sending the same email 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 email (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", "email"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
Session created.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"sid": "1234"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The session ID.
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error ocurred. Some possible errors are:
|
||||||
|
|
||||||
|
- ``M_INVALID_EMAIL``: The email address provided was invalid.
|
||||||
|
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
|
||||||
|
"/validate/email/submitToken":
|
||||||
|
post:
|
||||||
|
summary: Validate ownership of an email address.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of an email address.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the email address is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the email 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: emailSubmitTokenPost
|
||||||
|
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 emailed 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.
|
||||||
|
get:
|
||||||
|
summary: Validate ownership of an email address.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of an email address.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the email address is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the email address 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: emailSubmitTokenGet
|
||||||
|
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 emailed to the user.
|
||||||
|
x-example: atoken
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: Email address is validated.
|
||||||
|
"3xx":
|
||||||
|
description: |-
|
||||||
|
Email 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,90 @@
|
|||||||
|
# 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 Ephemeral Invitation Signing API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/identity/api/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/sign-ed25519":
|
||||||
|
post:
|
||||||
|
summary: Sign invitation details
|
||||||
|
description: |-
|
||||||
|
Sign invitation details.
|
||||||
|
|
||||||
|
The identity server will look up ``token`` which was stored in a call
|
||||||
|
to ``store-invite``, and fetch the sender of the invite.
|
||||||
|
operationId: blindlySignStuff
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"mxid": "@foo:bar.com",
|
||||||
|
"token": "sometoken",
|
||||||
|
"private_key": "base64encodedkey"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user accepting the invitation.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: Token from the call to ``store-invite``
|
||||||
|
private_key:
|
||||||
|
type: string
|
||||||
|
description: The private key, encoded as `Unpadded base64`_.
|
||||||
|
required: ["mxid", "token", "private_key"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The signedjson of the mxid, sender, and token.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user accepting the invitation.
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user who sent the invitation.
|
||||||
|
signatures:
|
||||||
|
type: object
|
||||||
|
description: The signature of the mxid, sender, and token.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token for the invitation.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"mxid": "@foo:bar.com",
|
||||||
|
"sender": "@baz:bar.com",
|
||||||
|
"signatures": {
|
||||||
|
"my.id.server": {
|
||||||
|
"ed25519:0": "def987"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"token": "abc123"
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: Token was not found.
|
||||||
|
example: {
|
||||||
|
"errcode": "M_UNRECOGNIZED",
|
||||||
|
"error": "Didn't recognize token"
|
||||||
|
}
|
||||||
@ -0,0 +1,114 @@
|
|||||||
|
# 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 Store Invitations API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/identity/api/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/store-invite":
|
||||||
|
post:
|
||||||
|
summary: Store pending invitations to a user\'s 3pid.
|
||||||
|
description: |-
|
||||||
|
Store pending invitations to a user\'s 3pid.
|
||||||
|
|
||||||
|
In addition to the request parameters specified below, an arbitrary
|
||||||
|
number of other parameters may also be specified. These may be used in
|
||||||
|
the invite message generation described below.
|
||||||
|
|
||||||
|
The service will generate a random token and an ephemeral key used for
|
||||||
|
accepting the invite.
|
||||||
|
|
||||||
|
The service also generates a ``display_name`` for the inviter, which is
|
||||||
|
a redacted version of ``address`` which does not leak the full contents
|
||||||
|
of the ``address``.
|
||||||
|
|
||||||
|
The service records persistently all of the above information.
|
||||||
|
|
||||||
|
It also generates an email containing all of this data, sent to the
|
||||||
|
``address`` parameter, notifying them of the invitation.
|
||||||
|
|
||||||
|
Also, the generated ephemeral public key will be listed as valid on
|
||||||
|
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
|
||||||
|
operationId: storeInvite
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"medium": "email",
|
||||||
|
"address": "foo@bar.baz",
|
||||||
|
"room_id": "!something:example.tld",
|
||||||
|
"sender": "@bob:example.com"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The literal string ``email``.
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The email address of the invited user.
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: The Matrix room ID to which the user is invited
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the inviting user
|
||||||
|
required: ["medium", "address", "room_id", "sender"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The invitation was stored.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The generated token.
|
||||||
|
public_keys:
|
||||||
|
type: array
|
||||||
|
description: A list of [server\'s long-term public key, generated ephemeral public key].
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
display_name:
|
||||||
|
type: string
|
||||||
|
description: The generated (redacted) display_name.
|
||||||
|
example:
|
||||||
|
application/json: {
|
||||||
|
"token": "sometoken",
|
||||||
|
"public_keys": [
|
||||||
|
"serverpublickey",
|
||||||
|
"ephemeralpublickey"
|
||||||
|
],
|
||||||
|
"display_name": "f...@b..."
|
||||||
|
}
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error has occured.
|
||||||
|
|
||||||
|
If the 3pid is already bound to a Matrix user ID, the error code
|
||||||
|
will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the
|
||||||
|
error code will be ``M_UNRECOGNIZED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_THREEPID_IN_USE",
|
||||||
|
"error": "Binding already known",
|
||||||
|
"mxid": mxid
|
||||||
|
}
|
||||||
@ -0,0 +1,148 @@
|
|||||||
|
# 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 Events API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8448
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/federation/v1
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/backfill/{roomId}":
|
||||||
|
get:
|
||||||
|
summary: Retrieves the events which precede the given event
|
||||||
|
description: |-
|
||||||
|
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
|
||||||
|
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
|
||||||
|
are retrieved, up to the total number given by the ``limit``.
|
||||||
|
operationId: backfillRoom
|
||||||
|
security:
|
||||||
|
- signedRequest: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: roomId
|
||||||
|
type: string
|
||||||
|
description: The room ID to backfill.
|
||||||
|
required: true
|
||||||
|
x-example: "!SomeRoom:matrix.org"
|
||||||
|
- in: query
|
||||||
|
name: v
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: The event IDs to backfill from.
|
||||||
|
required: true
|
||||||
|
x-example: ["$abc123:matrix.org"]
|
||||||
|
- in: query
|
||||||
|
name: limit
|
||||||
|
type: integer
|
||||||
|
description: The maximum number of PDUs to retrieve, including the given events.
|
||||||
|
required: true
|
||||||
|
x-example: 2
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
A transaction containing the PDUs that preceded the given event(s), including the given
|
||||||
|
event(s), up to the given limit.
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/transaction.yaml"
|
||||||
|
# Override the example to show the response of the request a bit better
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"$ref": "examples/transaction.json",
|
||||||
|
"pdus": [
|
||||||
|
{
|
||||||
|
"$ref": "pdu.json",
|
||||||
|
"room_id": "!SomeRoom:matrix.org",
|
||||||
|
"event_id": "$abc123:matrix.org"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"$ref": "pdu.json",
|
||||||
|
"room_id": "!SomeRoom:matrix.org"
|
||||||
|
},
|
||||||
|
]
|
||||||
|
}
|
||||||
|
"/get_missing_events/{roomId}":
|
||||||
|
post:
|
||||||
|
summary: Retrieves events that the sender is missing
|
||||||
|
description: |-
|
||||||
|
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
|
||||||
|
walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
|
||||||
|
and stopping at the ``limit``.
|
||||||
|
operationId: getMissingPreviousEvents
|
||||||
|
security:
|
||||||
|
- signedRequest: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: roomId
|
||||||
|
type: string
|
||||||
|
description: The room ID to search in.
|
||||||
|
required: true
|
||||||
|
x-example: "!SomeRoom:matrix.org"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
limit:
|
||||||
|
type: integer
|
||||||
|
description: The maximum number of events to retrieve. Defaults to 10.
|
||||||
|
example: 10
|
||||||
|
min_depth:
|
||||||
|
type: integer
|
||||||
|
description: The minimum depth of events to retrieve. Defaults to 0.
|
||||||
|
example: 0
|
||||||
|
earliest_events:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The latest events that the sender already has. These are skipped when retrieving
|
||||||
|
the previous events of ``latest_events``.
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: ["$missing_event:domain.com"]
|
||||||
|
latest_events:
|
||||||
|
type: array
|
||||||
|
description: The events to retrieve the previous events for.
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: ["$event_that_has_the_missing_event_as_a_previous_event:domain.com"]
|
||||||
|
required: ['earliest_events', 'latest_events']
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The previous events for ``latest_events``, excluding any ``earliest_events``, up to the
|
||||||
|
provided ``limit``.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
events:
|
||||||
|
type: array
|
||||||
|
description: The missing events.
|
||||||
|
items:
|
||||||
|
$ref: definitions/pdu.yaml
|
||||||
|
required: ['events']
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"events": [
|
||||||
|
{"$ref": "examples/pdu.json"}
|
||||||
|
]
|
||||||
|
}
|
||||||
@ -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: Typing Notification EDU
|
||||||
|
description: A typing notification EDU for a user in a room.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../edu.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
edu_type:
|
||||||
|
type: string
|
||||||
|
description: The string ``m.typing``
|
||||||
|
example: "m.typing"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
description: The typing notification.
|
||||||
|
title: Typing Notification
|
||||||
|
properties:
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The room where the user's typing status has been updated.
|
||||||
|
example: "!somewhere:matrix.org"
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The user ID that has had their typing status changed.
|
||||||
|
example: "@john:matrix.org"
|
||||||
|
typing:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the user is typing in the room or not.
|
||||||
|
example: true
|
||||||
|
required: ['room_id', 'user_id', 'typing']
|
||||||
@ -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 @@
|
|||||||
|
Add new user identifier object for logging in
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Document and improve client interaction with pushers.
|
||||||
@ -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.
|
||||||
|
|
||||||
|
OpenID
|
||||||
|
======
|
||||||
|
|
||||||
|
.. _module:openid:
|
||||||
|
|
||||||
|
This module allows users to verify their identity with a third party service. The
|
||||||
|
third party service does need to be matrix-aware in that it will need to know to
|
||||||
|
resolve matrix homeservers to exchange the user's token for identity information.
|
||||||
|
|
||||||
|
{{openid_cs_http_api}}
|
||||||
Loading…
Reference in New Issue