You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/identity/v2_store_invite.yaml

232 lines
9.3 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.
openapi: 3.1.0
info:
title: Matrix Identity Service Store Invitations API
version: 2.0.0
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. The email should
reference the `inviter_name`, `room_name`, `room_avatar`, and `room_type`
(if present) from the request here.
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:
- accessTokenQuery: []
- accessTokenBearer: []
requestBody:
content:
application/json:
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:example.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
room_type:
type: string
description: |-
The `type` from the `m.room.create` event's `content`. If the create event doesn't
have a specified `type`, this field is not included.
example: m.space
required:
- medium
- address
- room_id
- sender
responses:
"200":
description: The invitation was stored.
content:
application/json:
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: object
title: PublicKey
properties:
public_key:
type: string
description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url:
type: string
description: |
The URI of an endpoint where the validity of this key can be checked
by passing it as a `public_key` query parameter. See
[key management](/identity-service-api/#key-management).
required:
- public_key
- key_validity_url
display_name:
type: string
description: The generated (redacted) display name.
required:
- token
- public_keys
- display_name
examples:
response:
value: {
"token": "sometoken",
"public_keys": [
{
"public_key": "serverPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
},
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
"400":
description: |
An error has occurred.
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`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
"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](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer