afd5018494
Part of MSC2140 Convert status codes to strings if there is a string status code. Fixes a build error when we mix 4xx and 403 in the same definition. We also have to correct stringified numbers to pass the build.
176 lines
6.9 KiB
YAML
176 lines
6.9 KiB
YAML
# Copyright 2018 New Vector Ltd
|
|
# Copyright 2019 The Matrix.org Foundation C.I.C.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Identity Service Store Invitations API"
|
|
version: "2.0.0"
|
|
host: localhost:8090
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/identity/v2
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
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/v2/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: storeInviteV2
|
|
security:
|
|
- accessToken: []
|
|
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"
|
|
403:
|
|
description: |
|
|
The user must do something in order to use this endpoint. One example
|
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_TERMS_NOT_SIGNED",
|
|
"error": "Please accept our updated terms of service before continuing"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|