Remove v1 identity service API
Spec for https://github.com/matrix-org/matrix-doc/pull/2713pull/977/head
Travis Ralston
4 years ago
committed by
Richard van der Hoff
parent
457f3995af
commit
37c3a3f855
@ -1,302 +0,0 @@
|
|||||||
# 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
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
produces:
|
|
||||||
- application/json
|
|
||||||
paths:
|
|
||||||
"/3pid/getValidated3pid":
|
|
||||||
get:
|
|
||||||
summary: Check whether ownership of a 3pid was validated.
|
|
||||||
description: |-
|
|
||||||
Determines if a given 3pid has been validated by a user.
|
|
||||||
operationId: getValidated3pid
|
|
||||||
deprecated: true
|
|
||||||
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, in milliseconds, indicating the time that the 3pid
|
|
||||||
was validated.
|
|
||||||
required: ['medium', 'address', 'validated_at']
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
"/3pid/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 previous drafts of this
|
|
||||||
specification, the parameters may also be specified as
|
|
||||||
`application/x-form-www-urlencoded` data. However, this usage is
|
|
||||||
deprecated.
|
|
||||||
operationId: bind
|
|
||||||
deprecated: true
|
|
||||||
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 servers which show that the
|
|
||||||
association should be trusted, if you trust the verifying identity
|
|
||||||
services.
|
|
||||||
$ref: "../../schemas/server-signatures.yaml"
|
|
||||||
required:
|
|
||||||
- address
|
|
||||||
- medium
|
|
||||||
- mxid
|
|
||||||
- not_before
|
|
||||||
- not_after
|
|
||||||
- ts
|
|
||||||
- signatures
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
"/3pid/unbind":
|
|
||||||
post:
|
|
||||||
summary: Remove an association between a session and a Matrix user ID.
|
|
||||||
description: |-
|
|
||||||
Remove an association between a session and a Matrix user ID.
|
|
||||||
|
|
||||||
Future calls to `/lookup` for any of the session's 3pids will not
|
|
||||||
return the removed association.
|
|
||||||
|
|
||||||
The identity server should authenticate the request in one of two
|
|
||||||
ways:
|
|
||||||
|
|
||||||
1. The request is signed by the homeserver which controls the `user_id`.
|
|
||||||
2. The request includes the `sid` and `client_secret` parameters,
|
|
||||||
as per `/3pid/bind`, which proves ownership of the 3PID.
|
|
||||||
|
|
||||||
If this endpoint returns a JSON Matrix error, that error should be passed
|
|
||||||
through to the client requesting an unbind through a homeserver, if the
|
|
||||||
homeserver is acting on behalf of a client.
|
|
||||||
operationId: unbind
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: body
|
|
||||||
name: body
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
example: {
|
|
||||||
"sid": "1234",
|
|
||||||
"client_secret": "monkeys_are_GREAT",
|
|
||||||
"mxid": "@ears:example.org",
|
|
||||||
"threepid": {
|
|
||||||
"medium": "email",
|
|
||||||
"address": "monkeys_have_ears@example.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 remove from the 3pids.
|
|
||||||
threepid:
|
|
||||||
type: object
|
|
||||||
title: 3PID
|
|
||||||
description: |-
|
|
||||||
The 3PID to remove. Must match the 3PID used to generate the session
|
|
||||||
if using `sid` and `client_secret` to authenticate this request.
|
|
||||||
properties:
|
|
||||||
medium:
|
|
||||||
type: string
|
|
||||||
description: |-
|
|
||||||
A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
|
|
||||||
of the identifier to unbind.
|
|
||||||
address:
|
|
||||||
type: string
|
|
||||||
description: The 3PID address to remove.
|
|
||||||
required: ['medium', 'address']
|
|
||||||
required: ["threepid", "mxid"]
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: The association was successfully removed.
|
|
||||||
examples:
|
|
||||||
application/json: {}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
400:
|
|
||||||
description: |-
|
|
||||||
If the response body is not a JSON Matrix error, the identity server
|
|
||||||
does not support unbinds. If a JSON Matrix error is in the response
|
|
||||||
body, the requesting party should respect the error.
|
|
||||||
404:
|
|
||||||
description: |-
|
|
||||||
If the response body is not a JSON Matrix error, the identity server
|
|
||||||
does not support unbinds. If a JSON Matrix error is in the response
|
|
||||||
body, the requesting party should respect the error.
|
|
||||||
403:
|
|
||||||
description: |-
|
|
||||||
The credentials supplied to authenticate the request were invalid.
|
|
||||||
This may also be returned if the identity server does not support
|
|
||||||
the chosen authentication method (such as blocking homeservers from
|
|
||||||
unbinding identifiers).
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Invalid homeserver signature"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
501:
|
|
||||||
description: |-
|
|
||||||
If the response body is not a JSON Matrix error, the identity server
|
|
||||||
does not support unbinds. If a JSON Matrix error is in the response
|
|
||||||
body, the requesting party should respect the error.
|
|
||||||
@ -1,177 +0,0 @@
|
|||||||
# 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
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
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 server will send an email containing a token. If that
|
|
||||||
token is presented to the identity server 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 homeservers 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 previous drafts of this
|
|
||||||
specification, the parameters may also be specified as
|
|
||||||
`application/x-form-www-urlencoded` data. However, this usage is
|
|
||||||
deprecated.
|
|
||||||
operationId: emailRequestToken
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: body
|
|
||||||
name: body
|
|
||||||
schema:
|
|
||||||
$ref: "definitions/request_email_validation.yaml"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: Session created.
|
|
||||||
schema:
|
|
||||||
$ref: "definitions/sid.yaml"
|
|
||||||
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.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"errcode": "M_INVALID_EMAIL",
|
|
||||||
"error": "The email address is not valid"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
"/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.
|
|
||||||
|
|
||||||
The identity server is free to match the token case-insensitively, or
|
|
||||||
carry out other mapping operations such as unicode
|
|
||||||
normalisation. Whether to do so is an implementation detail for the
|
|
||||||
identity server. Clients must always pass on the token without
|
|
||||||
modification.
|
|
||||||
|
|
||||||
Note: for backwards compatibility with previous drafts of this
|
|
||||||
specification, the parameters may also be specified as
|
|
||||||
`application/x-form-www-urlencoded` data. However, this usage is
|
|
||||||
deprecated.
|
|
||||||
operationId: emailSubmitTokenPost
|
|
||||||
deprecated: true
|
|
||||||
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.
|
|
||||||
required: ['success']
|
|
||||||
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
|
|
||||||
deprecated: true
|
|
||||||
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.
|
|
||||||
@ -1,97 +0,0 @@
|
|||||||
# 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
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
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
|
|
||||||
deprecated: true
|
|
||||||
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: The token from the call to `store-invite`.
|
|
||||||
private_key:
|
|
||||||
type: string
|
|
||||||
description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
|
|
||||||
required: ["mxid", "token", "private_key"]
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: The signed JSON 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.
|
|
||||||
$ref: "../../schemas/server-signatures.yaml"
|
|
||||||
token:
|
|
||||||
type: string
|
|
||||||
description: The token for the invitation.
|
|
||||||
required: ['mxid', 'sender', 'signatures', 'token']
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"mxid": "@foo:bar.com",
|
|
||||||
"sender": "@baz:bar.com",
|
|
||||||
"signatures": {
|
|
||||||
"my.id.server": {
|
|
||||||
"ed25519:0": "def987"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"token": "abc123"
|
|
||||||
}
|
|
||||||
404:
|
|
||||||
description: The token was not found.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"errcode": "M_UNRECOGNIZED",
|
|
||||||
"error": "Didn't recognize token"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
@ -1,171 +0,0 @@
|
|||||||
# Copyright 2016 OpenMarket Ltd
|
|
||||||
# Copyright 2017 Kamax.io
|
|
||||||
# Copyright 2017 New Vector 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 Identity Service Lookup API"
|
|
||||||
version: "1.0.0"
|
|
||||||
host: localhost:8090
|
|
||||||
schemes:
|
|
||||||
- https
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
produces:
|
|
||||||
- application/json
|
|
||||||
paths:
|
|
||||||
"/lookup":
|
|
||||||
get:
|
|
||||||
summary: Look up the Matrix user ID for a 3pid.
|
|
||||||
description: Look up the Matrix user ID for a 3pid.
|
|
||||||
operationId: lookupUser
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: query
|
|
||||||
type: string
|
|
||||||
name: medium
|
|
||||||
required: true
|
|
||||||
description: The medium type of the 3pid. See the [3PID Types](/appendices/#3pid-types) Appendix.
|
|
||||||
x-example: "email"
|
|
||||||
- in: query
|
|
||||||
type: string
|
|
||||||
name: address
|
|
||||||
required: true
|
|
||||||
description: The address of the 3pid being looked up. See the [3PID Types](/appendices/#3pid-types) Appendix.
|
|
||||||
x-example: "louise@bobs.burgers"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description:
|
|
||||||
The association for that 3pid, or an empty object if no association is known.
|
|
||||||
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, matching the address requested.
|
|
||||||
medium:
|
|
||||||
type: string
|
|
||||||
description: A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium requested.
|
|
||||||
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 servers which show that the association should be trusted, if you trust the verifying identity servers.
|
|
||||||
$ref: "../../schemas/server-signatures.yaml"
|
|
||||||
required:
|
|
||||||
- address
|
|
||||||
- medium
|
|
||||||
- mxid
|
|
||||||
- not_before
|
|
||||||
- not_after
|
|
||||||
- ts
|
|
||||||
- signatures
|
|
||||||
"/bulk_lookup":
|
|
||||||
post:
|
|
||||||
summary: Lookup Matrix user IDs for a list of 3pids.
|
|
||||||
description: Lookup Matrix user IDs for a list of 3pids.
|
|
||||||
operationId: lookupUsers
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: body
|
|
||||||
name: body
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
example: {
|
|
||||||
"threepids":
|
|
||||||
[
|
|
||||||
["email","user@example.org"],
|
|
||||||
["msisdn", "123456789"],
|
|
||||||
["email","user2@example.org"]
|
|
||||||
]
|
|
||||||
}
|
|
||||||
properties:
|
|
||||||
threepids:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: array
|
|
||||||
title: 3PID mappings
|
|
||||||
minItems: 2
|
|
||||||
maxItems: 2
|
|
||||||
items:
|
|
||||||
# TODO: Give real names to these values. Adding a `title` does not work.
|
|
||||||
#- type: 3PID Medium
|
|
||||||
#- type: 3PID Address
|
|
||||||
- type: string
|
|
||||||
- type: string
|
|
||||||
description: |-
|
|
||||||
An array of arrays containing the [3PID Types](/appendices/#3pid-types) with the `medium`
|
|
||||||
in first position and the `address` in second position.
|
|
||||||
required:
|
|
||||||
- "threepids"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: A list of known 3PID mappings for the supplied 3PIDs.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"threepids": [
|
|
||||||
["email","user@example.org", "@bla:example.org"],
|
|
||||||
["msisdn", "123456789", "@blah2:example.com"]
|
|
||||||
]
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
threepids:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: array
|
|
||||||
title: 3PID mappings
|
|
||||||
minItems: 3
|
|
||||||
maxItems: 3
|
|
||||||
items:
|
|
||||||
# TODO: Give real names to these values. Adding a `title` does not work.
|
|
||||||
#- type: 3PID Medium
|
|
||||||
#- type: 3PID Address
|
|
||||||
#- type: Matrix User ID
|
|
||||||
- type: string
|
|
||||||
- type: string
|
|
||||||
- type: string
|
|
||||||
description: |-
|
|
||||||
An array of array containing the [3PID Types](/appendices/#3pid-types) with the `medium`
|
|
||||||
in first position, the `address` in second position and Matrix user
|
|
||||||
ID in third position.
|
|
||||||
required:
|
|
||||||
- "threepids"
|
|
||||||
@ -1,179 +0,0 @@
|
|||||||
# 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
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
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 server will send an SMS message containing a token. If
|
|
||||||
that token is presented to the identity server 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 homeservers 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 previous drafts of this
|
|
||||||
specification, the parameters may also be specified as
|
|
||||||
`application/x-form-www-urlencoded` data. However, this usage is
|
|
||||||
deprecated.
|
|
||||||
operationId: msisdnRequestToken
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: body
|
|
||||||
name: body
|
|
||||||
schema:
|
|
||||||
$ref: "definitions/request_msisdn_validation.yaml"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: Session created.
|
|
||||||
schema:
|
|
||||||
$ref: "definitions/sid.yaml"
|
|
||||||
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.
|
|
||||||
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
|
|
||||||
SMS to the provided country or region.
|
|
||||||
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.
|
|
||||||
|
|
||||||
The identity server is free to match the token case-insensitively, or
|
|
||||||
carry out other mapping operations such as unicode
|
|
||||||
normalisation. Whether to do so is an implementation detail for the
|
|
||||||
identity server. Clients must always pass on the token without
|
|
||||||
modification.
|
|
||||||
|
|
||||||
Note: for backwards compatibility with previous drafts of this
|
|
||||||
specification, the parameters may also be specified as
|
|
||||||
`application/x-form-www-urlencoded` data. However, this usage is
|
|
||||||
deprecated.
|
|
||||||
operationId: msisdnSubmitTokenPost
|
|
||||||
deprecated: true
|
|
||||||
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
|
|
||||||
deprecated: true
|
|
||||||
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.
|
|
||||||
@ -1,46 +0,0 @@
|
|||||||
# Copyright 2018 Kamax Sàrl
|
|
||||||
# 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 Ping API"
|
|
||||||
version: "1.0.0"
|
|
||||||
host: localhost:8090
|
|
||||||
schemes:
|
|
||||||
- https
|
|
||||||
basePath: /_matrix/identity
|
|
||||||
produces:
|
|
||||||
- application/json
|
|
||||||
paths:
|
|
||||||
"/api/v1":
|
|
||||||
get:
|
|
||||||
summary: Checks that an identity server is available at this API endpoint.
|
|
||||||
description: |-
|
|
||||||
Checks that an identity server is available at this API endpoint.
|
|
||||||
|
|
||||||
To discover that an identity server is available at a specific URL,
|
|
||||||
this endpoint can be queried and will return an empty object.
|
|
||||||
|
|
||||||
This is primarly used for auto-discovery and health check purposes
|
|
||||||
by entities acting as a client for the identity server.
|
|
||||||
operationId: ping
|
|
||||||
deprecated: true
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: An identity server is ready to serve requests.
|
|
||||||
examples:
|
|
||||||
application/json: {}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
@ -1,129 +0,0 @@
|
|||||||
# Copyright 2016 OpenMarket Ltd
|
|
||||||
#
|
|
||||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
||||||
# you may not use this file except in compliance with the License.
|
|
||||||
# You may obtain a copy of the License at
|
|
||||||
#
|
|
||||||
# http://www.apache.org/licenses/LICENSE-2.0
|
|
||||||
#
|
|
||||||
# Unless required by applicable law or agreed to in writing, software
|
|
||||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
||||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
||||||
# See the License for the specific language governing permissions and
|
|
||||||
# limitations under the License.
|
|
||||||
swagger: '2.0'
|
|
||||||
info:
|
|
||||||
title: "Matrix Identity Service Public Key API"
|
|
||||||
version: "1.0.0"
|
|
||||||
host: localhost:8090
|
|
||||||
schemes:
|
|
||||||
- https
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
produces:
|
|
||||||
- application/json
|
|
||||||
paths:
|
|
||||||
"/pubkey/{keyId}":
|
|
||||||
get:
|
|
||||||
summary: Get a public key.
|
|
||||||
description: |-
|
|
||||||
Get the public key for the passed key ID.
|
|
||||||
operationId: getPubKey
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: path
|
|
||||||
type: string
|
|
||||||
name: keyId
|
|
||||||
required: true
|
|
||||||
description: |-
|
|
||||||
The ID of the key. This should take the form algorithm:identifier
|
|
||||||
where algorithm identifies the signing algorithm, and the identifier
|
|
||||||
is an opaque string.
|
|
||||||
x-example: "ed25519:0"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description:
|
|
||||||
The public key exists.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
public_key:
|
|
||||||
type: string
|
|
||||||
description: Unpadded Base64 encoded public key.
|
|
||||||
required: ['public_key']
|
|
||||||
404:
|
|
||||||
description:
|
|
||||||
The public key was not found.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"errcode": "M_NOT_FOUND",
|
|
||||||
"error": "The public key was not found"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
"/pubkey/isvalid":
|
|
||||||
get:
|
|
||||||
summary: Check whether a long-term public key is valid.
|
|
||||||
description: |-
|
|
||||||
Check whether a long-term public key is valid. The response should always
|
|
||||||
be the same, provided the key exists.
|
|
||||||
operationId: isPubKeyValid
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: query
|
|
||||||
type: string
|
|
||||||
name: public_key
|
|
||||||
required: true
|
|
||||||
description: |-
|
|
||||||
The unpadded base64-encoded public key to check.
|
|
||||||
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description:
|
|
||||||
The validity of the public key.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"valid": true
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
valid:
|
|
||||||
type: boolean
|
|
||||||
description: Whether the public key is recognised and is currently valid.
|
|
||||||
required: ['valid']
|
|
||||||
"/pubkey/ephemeral/isvalid":
|
|
||||||
get:
|
|
||||||
summary: Check whether a short-term public key is valid.
|
|
||||||
description: |-
|
|
||||||
Check whether a short-term public key is valid.
|
|
||||||
operationId: isEphemeralPubKeyValid
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: query
|
|
||||||
type: string
|
|
||||||
name: public_key
|
|
||||||
required: true
|
|
||||||
description: |-
|
|
||||||
The unpadded base64-encoded public key to check.
|
|
||||||
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description:
|
|
||||||
The validity of the public key.
|
|
||||||
examples:
|
|
||||||
application/json: {
|
|
||||||
"valid": true
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
valid:
|
|
||||||
type: boolean
|
|
||||||
description: Whether the public key is recognised and is currently valid.
|
|
||||||
required: ['valid']
|
|
||||||
@ -1,161 +0,0 @@
|
|||||||
# 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
|
|
||||||
basePath: /_matrix/identity/api/v1
|
|
||||||
consumes:
|
|
||||||
- application/json
|
|
||||||
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`.
|
|
||||||
|
|
||||||
Currently, invites may only be issued for 3pids of the `email` medium.
|
|
||||||
|
|
||||||
Optional fields in the request should be populated to the best of the
|
|
||||||
server's ability. Identity servers may use these variables when notifying
|
|
||||||
the `address` of the pending invite for display purposes.
|
|
||||||
operationId: storeInvite
|
|
||||||
deprecated: true
|
|
||||||
parameters:
|
|
||||||
- in: body
|
|
||||||
name: body
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
medium:
|
|
||||||
type: string
|
|
||||||
description: The literal string `email`.
|
|
||||||
example: "email"
|
|
||||||
address:
|
|
||||||
type: string
|
|
||||||
description: The email address of the invited user.
|
|
||||||
example: "foo@example.com"
|
|
||||||
room_id:
|
|
||||||
type: string
|
|
||||||
description: The Matrix room ID to which the user is invited
|
|
||||||
example: "!something:example.org"
|
|
||||||
sender:
|
|
||||||
type: string
|
|
||||||
description: The Matrix user ID of the inviting user
|
|
||||||
example: "@bob:example.com"
|
|
||||||
room_alias:
|
|
||||||
type: string
|
|
||||||
description: |-
|
|
||||||
The Matrix room alias for the room to which the user is
|
|
||||||
invited. This should be retrieved from the `m.room.canonical_alias`
|
|
||||||
state event.
|
|
||||||
example: "#somewhere:exmaple.org"
|
|
||||||
room_avatar_url:
|
|
||||||
type: string
|
|
||||||
description: |-
|
|
||||||
The Content URI for the room to which the user is invited. This should
|
|
||||||
be retrieved from the `m.room.avatar` state event.
|
|
||||||
example: "mxc://example.org/s0meM3dia"
|
|
||||||
room_join_rules:
|
|
||||||
type: string
|
|
||||||
description: |-
|
|
||||||
The `join_rule` for the room to which the user is invited. This should
|
|
||||||
be retrieved from the `m.room.join_rules` state event.
|
|
||||||
example: "public"
|
|
||||||
room_name:
|
|
||||||
type: string
|
|
||||||
description: |-
|
|
||||||
The name of the room to which the user is invited. This should be retrieved
|
|
||||||
from the `m.room.name` state event.
|
|
||||||
example: "Bob's Emporium of Messages"
|
|
||||||
sender_display_name:
|
|
||||||
type: string
|
|
||||||
description: The display name of the user ID initiating the invite.
|
|
||||||
example: "Bob Smith"
|
|
||||||
sender_avatar_url:
|
|
||||||
type: string
|
|
||||||
description: The Content URI for the avatar of the user ID initiating the invite.
|
|
||||||
example: "mxc://example.org/an0th3rM3dia"
|
|
||||||
required: ["medium", "address", "room_id", "sender"]
|
|
||||||
responses:
|
|
||||||
200:
|
|
||||||
description: The invitation was stored.
|
|
||||||
schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
token:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The generated token. Must be a string consisting of the
|
|
||||||
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
|
|
||||||
255 characters and it must not be empty.
|
|
||||||
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.
|
|
||||||
required: ['token', 'public_keys', '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": "@alice:example.com"
|
|
||||||
}
|
|
||||||
schema:
|
|
||||||
$ref: "../client-server/definitions/errors/error.yaml"
|
|
||||||
Loading…
Reference in New Issue