wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add a hyphen between third and party when used as an adjective (#1447)

Browse source
This commit is contained in:
Andrew Morgan 2023-03-08 09:58:29 +00:00 • committed by GitHub
parent 9ebcf5f257
commit c0955a6aee
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
37 changed files with 190 additions and 187 deletions
Download patch file Download diff file Expand all files Collapse all files

2
attic/drafts/model/rooms.rst
View file

@ -246,7 +246,7 @@ anyway.
In this arrangement there is now a room with both users may join but neither has
the power to invite any others. Both users now have the confidence that (at
least within the messaging system itself) their messages remain private and
cannot later be provably leaked to a third party. They can freely set the topic
cannot later be provably leaked to a third-party. They can freely set the topic
or name if they choose and add or edit any other state of the room. The update
powerlevel of each of these fixed properties should be 1, to lock out the users
from being able to alter them.

12
attic/drafts/model/third-party-id.rst
View file

@ -1,9 +1,9 @@
======================
Third Party Identities
Third-party Identities
======================
A description of how email addresses, mobile phone numbers and other third
party identifiers can be used to authenticate and discover users in Matrix.
A description of how email addresses, mobile phone numbers and other third-party
identifiers can be used to authenticate and discover users in Matrix.
Overview
@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate
with those contacts in Matrix without manually exchanging a Matrix User ID with
them.
Third Party IDs
Third-party IDs
---------------
[[TODO(markjh): Describe the format of a 3PID]]
Third Party ID Associations
Third-party ID Associations
---------------------------
An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID).
An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID).
Each 3PID can be associated with one Matrix User ID at a time.
[[TODO(markjh): JSON format of the association.]]

1
changelogs/application_service/newsfragments/1447.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1447.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification.

2
changelogs/legacy/application_service.rst
View file

@ -22,5 +22,5 @@ r0.1.0
This is the first release of the Application Service specification. It
includes support for application services being able to interact with
homeservers and bridge third party networks, such as IRC, over to Matrix
homeservers and bridge third-party networks, such as IRC, over to Matrix
in a standard and accessible way.

4
changelogs/legacy/client_server.rst
View file

@ -211,7 +211,7 @@ Backwards Compatible Changes
- Add a common standard for user, room, and group mentions in messages. (`#1547 <https://github.com/matrix-org/matrix-doc/issues/1547>`_)
- Add server ACLs as an option for controlling federation in a room. (`#1550 <https://github.com/matrix-org/matrix-doc/issues/1550>`_)
- Add new push rules for encrypted events and ``@room`` notifications. (`#1551 <https://github.com/matrix-org/matrix-doc/issues/1551>`_)
- Add third party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
- Add third-party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
- Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 <https://github.com/matrix-org/matrix-doc/issues/1567>`_)
- Add an ``inhibit_login`` registration option. (`#1589 <https://github.com/matrix-org/matrix-doc/issues/1589>`_)
- Recommend that servers set a Content Security Policy for the content repository. (`#1600 <https://github.com/matrix-org/matrix-doc/issues/1600>`_)
@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made:
- Push notification
- History visibility
- Search
- Invites based on third party identifiers
- Invites based on third-party identifiers
- Room tagging
- Guest access
- Client config

4
changelogs/legacy/identity_service.rst
View file

@ -48,7 +48,7 @@ r0.1.0
======
This is the first release of the Identity Service API. With this API, clients and
homeservers can store bindings between third party identifiers such as email addresses
homeservers can store bindings between third-party identifiers such as email addresses
and phone numbers, associating them with Matrix user IDs. Additionally, identity
servers offer the ability to invite third party users to Matrix rooms by storing
servers offer the ability to invite third-party users to Matrix rooms by storing
the invite until the identifier is bound.

1
changelogs/server_server/newsfragments/1447.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification.

2
content/_index.md
View file

@ -372,7 +372,7 @@ servers that are in the room that can be used to join via.
Users in Matrix are identified via their Matrix user ID. However,
existing 3rd party ID namespaces can also be used in order to identify
Matrix users. A Matrix "Identity" describes both the user ID and any
other existing IDs from third party namespaces *linked* to their
other existing IDs from third-party namespaces *linked* to their
account. Matrix users can *link* third-party IDs (3PIDs) such as email
addresses, social network accounts and phone numbers to their user ID.
Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping

2
content/appendices.md
View file

@ -892,7 +892,7 @@ unique servers based on the following criteria:
## 3PID Types
Third Party Identifiers (3PIDs) represent identifiers on other
Third-party Identifiers (3PIDs) represent identifiers on other
namespaces that might be associated with a particular person. They
comprise a tuple of `medium` which is a string that identifies the
namespace in which the identifier exists, and an `address`: a string

12
content/application-service-api.md
View file

@ -232,18 +232,18 @@ mappings.
{{% http-api spec="application-service" api="query_room" %}}
#### Third party networks
#### Third-party networks
Application services may declare which protocols they support via their
registration configuration for the homeserver. These networks are
generally for third party services such as IRC that the application
generally for third-party services such as IRC that the application
service is managing. Application services may populate a Matrix room
directory for their registered protocols, as defined in the
Client-Server API Extensions.
Each protocol may have several "locations" (also known as "third party
Each protocol may have several "locations" (also known as "third-party
locations" or "3PLs"). A location within a protocol is a place in the
third party network, such as an IRC channel. Users of the third party
third-party network, such as an IRC channel. Users of the third-party
network may also be represented by the application service.
Locations and users can be searched by fields defined by the application
@ -399,13 +399,13 @@ the user implied by `sender_localpart`.
#### Application service room directories
Application services can maintain their own room directories for their
defined third party protocols. These room directories may be accessed by
defined third-party protocols. These room directories may be accessed by
clients through additional parameters on the `/publicRooms`
client-server endpoint.
{{% http-api spec="client-server" api="appservice_room_directory" %}}
### Referencing messages from a third party network
### Referencing messages from a third-party network
Application services should include an `external_url` in the `content`
of events it emits to indicate where the message came from. This

22
content/client-server-api/_index.md
View file

@ -150,15 +150,15 @@ Sent when a threepid given to an API cannot be used because no record
matching the threepid was found.
`M_THREEPID_AUTH_FAILED`
Authentication could not be performed on the third party identifier.
Authentication could not be performed on the third-party identifier.
`M_THREEPID_DENIED`
The server does not permit this third party identifier. This may happen
The server does not permit this third-party identifier. This may happen
if the server only permits, for example, email addresses from a
particular domain.
`M_SERVER_NOT_TRUSTED`
The client's request used a third party server, e.g. identity server,
The client's request used a third-party server, e.g. identity server,
that this server does not trust.
`M_UNSUPPORTED_ROOM_VERSION`
@ -764,8 +764,8 @@ explicitly as follows:
"type": "m.login.password",
"identifier": {
"type": "m.id.thirdparty",
"medium": "<The medium of the third party identifier.>",
"address": "<The third party address of the user>"
"medium": "<The medium of the third-party identifier.>",
"address": "<The third-party address of the user>"
},
"password": "<password>",
"session": "<session ID>"
@ -1071,8 +1071,8 @@ ID media.
```json
"identifier": {
"type": "m.id.thirdparty",
"medium": "<The medium of the third party identifier>",
"address": "<The canonicalised third party address of the user>"
"medium": "<The medium of the third-party identifier>",
"address": "<The canonicalised third-party address of the user>"
}
```
@ -1132,8 +1132,8 @@ the homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API r
{
"type": "m.login.password",
"identifier": {
"medium": "<The medium of the third party identifier>",
"address": "<The canonicalised third party address of the user>"
"medium": "<The medium of the third-party identifier>",
"address": "<The canonicalised third-party address of the user>"
},
"password": "<password>"
}
@ -1258,7 +1258,7 @@ can be added and bound at the same time, depending on context.
#### Notes on identity servers
Identity servers in Matrix store bindings (relationships) between a
user's third party identifier, typically email or phone number, and
user's third-party identifier, typically email or phone number, and
their user ID. Once a user has chosen an identity server, that identity
server should be used by all clients.
@ -2566,7 +2566,7 @@ that profile.
| [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional |
| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional |
| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional |
| [Third Party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional |
| [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional |
| [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional |

4
content/client-server-api/modules/openid.md
View file

@ -1,8 +1,8 @@
### 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
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.

36
content/client-server-api/modules/third_party_invites.md
View file

@ -1,12 +1,12 @@
### Third party invites
### Third-party invites
This module adds in support for inviting new members to a room where
their Matrix user ID is not known, instead addressing them by a third
party identifier such as an email address. There are two flows here; one
if a Matrix user ID is known for the third party identifier, and one if
their Matrix user ID is not known, instead addressing them by a third-party
identifier such as an email address. There are two flows here; one
if a Matrix user ID is known for the third-party identifier, and one if
not. Either way, the client calls `/invite` with the details of the
third party identifier.
third-party identifier.
The homeserver asks the identity server whether a Matrix user ID is
known for that identifier:
@ -22,7 +22,7 @@ When the invitee's homeserver receives the notification of the binding,
it should insert an `m.room.member` event into the room's graph for that
user, with `content.membership` = `invite`, as well as a
`content.third_party_invite` property which contains proof that the
invitee does indeed own that third party identifier. See the
invitee does indeed own that third-party identifier. See the
[m.room.member](#mroommember) schema for more information.
#### Events
@ -31,14 +31,14 @@ invitee does indeed own that third party identifier. See the
#### Client behaviour
A client asks a server to invite a user by their third party identifier.
A client asks a server to invite a user by their third-party identifier.
{{% http-api spec="client-server" api="third_party_membership" %}}
#### Server behaviour
Upon receipt of an `/invite`, the server is expected to look up the
third party identifier with the provided identity server. If the lookup
third-party identifier with the provided identity server. If the lookup
yields a result for a Matrix User ID then the normal invite process can
be initiated. This process ends up looking like this:
@ -104,12 +104,12 @@ looking like this:
All homeservers MUST verify the signature in the event's
`content.third_party_invite.signed` object.
The third party user will then need to verify their identity, which
The third-party user will then need to verify their identity, which
results in a call from the identity server to the homeserver that bound
the third party identifier to a user. The homeserver then exchanges the
the third-party identifier to a user. The homeserver then exchanges the
`m.room.third_party_invite` event in the room for a complete
`m.room.member` event for `membership: invite` for the user that has
bound the third party identifier.
bound the third-party identifier.
If a homeserver is joining a room for the first time because of an
`m.room.third_party_invite`, the server which is already participating
@ -123,7 +123,7 @@ view of the room. They may, however, indicate to their clients that a
member's membership is questionable.
For example, given H1, H2, and H3 as homeservers, UserA as a user of H1,
and an identity server IS, the full sequence for a third party invite
and an identity server IS, the full sequence for a third-party invite
would look like the following. This diagram assumes H1 and H2 are
residents of the room while H3 is attempting to join.
@ -144,7 +144,7 @@ residents of the room while H3 is attempting to join.
| | | POST /store-invite | | |
| | |---------------------------------------------------------------------------------------------->|
| | | | | |
| | | | Token, keys, etc for third party invite |
| | | | Token, keys, etc for third-party invite |
| | |<----------------------------------------------------------------------------------------------|
| | | | | |
| | | (Federation) Emit m.room.third_party_invite | | |
@ -214,13 +214,13 @@ still be performed, so the attack surface here is minimized.
There are a number of privacy and trust implications to this module.
It is important for user privacy that leaking the mapping between a
matrix user ID and a third party identifier is hard. In particular,
being able to look up all third party identifiers from a matrix user ID
(and accordingly, being able to link each third party identifier) should
be avoided wherever possible. To this end, the third party identifier is
matrix user ID and a third-party identifier is hard. In particular,
being able to look up all third-party identifiers from a matrix user ID
(and accordingly, being able to link each third-party identifier) should
be avoided wherever possible. To this end, the third-party identifier is
not put in any event, rather an opaque display name provided by the
identity server is put into the events. Clients should not remember or
display third party identifiers from invites, other than for the use of
display third-party identifiers from invites, other than for the use of
the inviter themself.
Homeservers are not required to trust any particular identity server(s).

16
content/client-server-api/modules/third_party_networks.md
View file

@ -1,18 +1,18 @@
### Third Party Networks
### Third-party Networks
Application services can provide access to third party networks via
Application services can provide access to third-party networks via
bridging. This allows Matrix users to communicate with users on other
communication platforms, with messages ferried back and forth by the
application service. A single application service may bridge multiple
third party networks, and many individual locations within those
networks. A single third party network location may be bridged to
third-party networks, and many individual locations within those
networks. A single third-party network location may be bridged to
multiple Matrix rooms.
#### Third Party Lookups
#### Third-party Lookups
A client may wish to provide a rich interface for joining third party
locations and connecting with third party users. Information necessary
for such an interface is provided by third party lookups.
A client may wish to provide a rich interface for joining third-party
locations and connecting with third-party users. Information necessary
for such an interface is provided by third-party lookups.
{{% http-api spec="client-server" api="third_party_lookup" %}}

10
content/identity-service-api.md
View file

@ -98,11 +98,11 @@ There was an error sending an email. Typically seen when attempting to
verify ownership of a given email address.
`M_INVALID_ADDRESS`
The provided third party address was not valid.
The provided third-party address was not valid.
`M_SEND_ERROR`
There was an error sending a notification. Typically seen when
attempting to verify ownership of a given third party address.
attempting to verify ownership of a given third-party address.
`M_UNRECOGNIZED`
The request contained an unrecognised value, such as an unknown token or
@ -114,9 +114,9 @@ not implemented or a 405 HTTP status code if the endpoint is implemented, but
the incorrect HTTP method is used.
`M_THREEPID_IN_USE`
The third party identifier is already in use by another user. Typically
The third-party identifier is already in use by another user. Typically
this error will have an additional `mxid` property to indicate who owns
the third party identifier.
the third-party identifier.
`M_UNKNOWN`
An unknown error has occurred.
@ -369,7 +369,7 @@ To start a session, the client makes a request to the appropriate
token to the user, and the user provides the token to the client. The
client then provides the token to the appropriate `/submitToken`
endpoint, completing the session. At this point, the client should
`/bind` the third party identifier or leave it for another entity to
`/bind` the third-party identifier or leave it for another entity to
bind.
### Format of a validation token

6
content/server-server-api.md
View file

@ -938,9 +938,9 @@ the event to other servers in the room.
## Third-party invites
{{% boxes/note %}}
More information about third party invites is available in the
More information about third-party invites is available in the
[Client-Server API](/client-server-api) under
the Third Party Invites module.
the Third-party Invites module.
{{% /boxes/note %}}
When a user wants to invite another user in a room but doesn't know the
@ -1076,7 +1076,7 @@ more specific queries that can be made.
## OpenID
Third party services can exchange an access token previously generated
Third-party services can exchange an access token previously generated
by the <span class="title-ref">Client-Server API</span> for information
about a user. This can help verify that a user is who they say they are
without granting full access to the user's account.

4
data/api/application-service/definitions/location.yaml
View file

@ -17,11 +17,11 @@ properties:
type: string
example: "#freenode_#matrix:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
description: The protocol ID that the third-party location is a part of.
type: string
example: "irc"
fields:
description: Information used to identify this third party location.
description: Information used to identify this third-party location.
type: object
example: {
"network": "freenode",

2
data/api/application-service/definitions/location_batch.yaml
View file

@ -12,6 +12,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party locations.
description: List of matched third-party locations.
items:
$ref: location.yaml

10
data/api/application-service/definitions/protocol.yaml
View file

@ -16,28 +16,28 @@ type: object
properties:
user_fields:
description: |-
Fields which may be used to identify a third party user. These should be
Fields which may be used to identify a third-party user. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the nickname of a user.
type: array
items:
type: string
description: Field used to identify a third party user.
description: Field used to identify a third-party user.
example: ["network", "nickname"]
location_fields:
description: |-
Fields which may be used to identify a third party location. These should be
Fields which may be used to identify a third-party location. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the name of a channel.
type: array
items:
type: string
description: Field used to identify a third party location.
description: Field used to identify a third-party location.
example: ["network", "channel"]
icon:
description: A content URI representing an icon for the third party protocol.
description: A content URI representing an icon for the third-party protocol.
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:

2
data/api/application-service/definitions/protocol_metadata.yaml
View file

@ -12,7 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: Dictionary of supported third party protocols.
description: Dictionary of supported third-party protocols.
additionalProperties:
$ref: protocol.yaml
example: {

6
data/api/application-service/definitions/user.yaml
View file

@ -15,15 +15,15 @@
# TODO: Change userid to user_id as a breaking change
properties:
userid:
description: A Matrix User ID represting a third party user.
description: A Matrix User ID represting a third-party user.
type: string
example: "@_gitter_jim:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
description: The protocol ID that the third-party location is a part of.
type: string
example: "gitter"
fields:
description: Information used to identify this third party location.
description: Information used to identify this third-party location.
type: object
example: {
"user": "jim"

2
data/api/application-service/definitions/user_batch.yaml
View file

@ -12,6 +12,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party users.
description: List of matched third-party users.
items:
$ref: user.yaml

24
data/api/application-service/protocols.yaml
View file

@ -32,7 +32,7 @@ paths:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
This API is called by the homeserver when it wants to present clients
with specific information about the various third party networks that
with specific information about the various third-party networks that
an application service supports.
operationId: getProtocolMetadata
security:
@ -78,10 +78,10 @@ paths:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
summary: Retrieve the Matrix User ID of a corresponding third-party user.
description: |-
This API is called by the homeserver in order to retrieve a Matrix
User ID linked to a user on the third party network, given a set of
User ID linked to a user on the third-party network, given a set of
user parameters.
operationId: queryUserByProtocol
security:
@ -133,9 +133,9 @@ paths:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portal rooms leading to a third party location.
summary: Retrieve Matrix-side portal rooms leading to a third-party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
Retrieve a list of Matrix portal rooms that lead to the matched third-party location.
operationId: queryLocationByProtocol
security:
- homeserverAccessToken: []
@ -151,7 +151,7 @@ paths:
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the third party location.
service to help identify the third-party location.
responses:
200:
description: At least one portal room was found.
@ -186,9 +186,9 @@ paths:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
Retrieve an array of third-party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
@ -201,7 +201,7 @@ paths:
responses:
200:
description: |-
All found third party locations.
All found third-party locations.
schema:
$ref: definitions/location_batch.yaml
401:
@ -233,9 +233,9 @@ paths:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
summary: Reverse-lookup third-party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
Retrieve an array of third-party users from a Matrix User ID.
operationId: queryUserByID
security:
- homeserverAccessToken: []
@ -247,7 +247,7 @@ paths:
responses:
200:
description: |-
An array of third party users.
An array of third-party users.
schema:
$ref: definitions/user_batch.yaml
401:

54
data/api/client-server/administrative_contact.yaml
View file

@ -30,12 +30,12 @@ securityDefinitions:
paths:
"/account/3pid":
get:
summary: Gets a list of a user's third party identifiers.
summary: Gets a list of a user's third-party identifiers.
description: |-
Gets a list of the third party identifiers that the homeserver has
Gets a list of the third-party identifiers that the homeserver has
associated with the user's account.
This is *not* the same as the list of third party identifiers bound to
This is *not* the same as the list of third-party identifiers bound to
the user's Matrix ID in identity servers.
Identifiers in this list may be used by the homeserver as, for example,
@ -64,15 +64,15 @@ paths:
type: array
items:
type: object
title: Third party identifier
title: Third-party identifier
properties:
medium:
type: string
description: The medium of the third party identifier.
description: The medium of the third-party identifier.
enum: ["email", "msisdn"]
address:
type: string
description: The third party identifier address.
description: The third-party identifier address.
validated_at:
type: integer
format: int64
@ -84,7 +84,7 @@ paths:
format: int64
description:
The timestamp, in milliseconds, when the homeserver
associated the third party identifier with the user.
associated the third-party identifier with the user.
required: ['medium', 'address', 'validated_at', 'added_at']
tags:
- Account management
@ -115,7 +115,7 @@ paths:
three_pid_creds:
title: "ThreePidCredentials"
type: object
description: The third party credentials to associate with the account.
description: The third-party credentials to associate with the account.
properties:
client_secret:
type: string
@ -174,7 +174,7 @@ paths:
examples:
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
"error": "The third-party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
@ -290,9 +290,9 @@ paths:
- Account management
"/account/3pid/delete":
post:
summary: Deletes a third party identifier from the user's account
summary: Deletes a third-party identifier from the user's account
description: |-
Removes a third party identifier from the user's account. This might not
Removes a third-party identifier from the user's account. This might not
cause an unbind of the identifier from the identity server.
Unlike other endpoints, this endpoint does not take an `id_access_token`
@ -318,18 +318,18 @@ paths:
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third party address being removed.
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
responses:
200:
description: |-
The homeserver has disassociated the third party identifier from the
The homeserver has disassociated the third-party identifier from the
user.
schema:
type: object
@ -355,9 +355,9 @@ paths:
- Account management
"/account/3pid/unbind":
post:
summary: Removes a user's third party identifier from an identity server.
summary: Removes a user's third-party identifier from an identity server.
description: |-
Removes a user's third party identifier from the provided identity server
Removes a user's third-party identifier from the provided identity server
without removing it from the homeserver.
Unlike other endpoints, this endpoint does not take an `id_access_token`
@ -383,18 +383,18 @@ paths:
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third party address being removed.
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
responses:
200:
description: |-
The identity server has disassociated the third party identifier from the
The identity server has disassociated the third-party identifier from the
user.
schema:
type: object
@ -446,18 +446,18 @@ paths:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The third party identifier is already in use on the homeserver, or
The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
@ -466,7 +466,7 @@ paths:
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third party identifier already in use"
"error": "Third-party identifier already in use"
}
tags:
- Account management
@ -496,18 +496,18 @@ paths:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The third party identifier is already in use on the homeserver, or
The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
@ -516,7 +516,7 @@ paths:
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third party identifier already in use"
"error": "Third-party identifier already in use"
}
tags:
- Account management

6
data/api/client-server/create_room.yaml
View file

@ -138,7 +138,7 @@ paths:
invite_3pid:
type: array
description: |-
A list of objects representing third party IDs to invite into
A list of objects representing third-party IDs to invite into
the room.
items:
type: object
@ -146,7 +146,7 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
id_access_token:
type: string
description: |-
@ -160,7 +160,7 @@ paths:
(see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third party identifier.
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
room_version:
type: string

4
data/api/client-server/definitions/third_party_signed.yaml
View file

@ -12,10 +12,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Third Party Signed
title: Third-party Signed
description: |-
A signature of an `m.third_party_invite` token to prove that this user
owns a third party identity which has been invited to the room.
owns a third-party identity which has been invited to the room.
properties:
sender:
type: string

2
data/api/client-server/inviting.yaml
View file

@ -36,7 +36,7 @@ paths:
*Note that there are two forms of this API, which are documented separately.
This version of the API requires that the inviter knows the Matrix
identifier of the invitee. The other is documented in the
[third party invites](/client-server-api/#third-party-invites) section.*
[third-party invites](/client-server-api/#third-party-invites) section.*
This API invites a user to participate in a particular room.
They do not start participating in the room until they actually join the

2
data/api/client-server/list_public_rooms.yaml
View file

@ -219,7 +219,7 @@ paths:
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
example: "irc"
example: {

4
data/api/client-server/login.yaml
View file

@ -107,10 +107,10 @@ paths:
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`.
medium:
type: string
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
address:
type: string
description: Third party identifier for the user. Deprecated in favour of `identifier`.
description: Third-party identifier for the user. Deprecated in favour of `identifier`.
password:
type: string
description: |-

16
data/api/client-server/registration.yaml
View file

@ -272,7 +272,7 @@ paths:
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
@ -324,7 +324,7 @@ paths:
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
@ -443,18 +443,18 @@ paths:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The referenced third party identifier is not recognised by the
The referenced third-party identifier is not recognised by the
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
@ -500,18 +500,18 @@ paths:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The referenced third party identifier is not recognised by the
The referenced third-party identifier is not recognised by the
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.

42
data/api/client-server/third_party_lookup.yaml
View file

@ -13,7 +13,7 @@
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Third Party Lookup API"
title: "Matrix Client-Server Third-party Lookup API"
version: "1.0.0"
host: localhost:8008
schemes:
@ -43,12 +43,12 @@ paths:
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
tags:
- Third Party Lookup
- Third-party Lookup
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the homeserver supports.
description: |-
Fetches the metadata from the homeserver about a particular third party protocol.
Fetches the metadata from the homeserver about a particular third-party protocol.
operationId: getProtocolMetadata
security:
- accessToken: []
@ -74,16 +74,16 @@ paths:
schema:
$ref: definitions/errors/error.yaml
tags:
- Third Party Lookup
- Third-party Lookup
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portals rooms leading to a third party location.
summary: Retrieve Matrix-side portals rooms leading to a third-party location.
description: |-
Requesting this endpoint with a valid protocol name results in a list
of successful mapping results in a JSON array. Each result contains
objects to represent the Matrix room or rooms that represent a portal
to this third party network. Each has the Matrix room alias string,
an identifier for the particular third party network protocol, and an
to this third-party network. Each has the Matrix room alias string,
an identifier for the particular third-party network protocol, and an
object containing the network-specific fields that comprise this
identifier. It should attempt to canonicalise the identifier as much
as reasonably possible given the network type.
@ -94,14 +94,14 @@ paths:
- in: path
name: protocol
type: string
description: The protocol used to communicate to the third party network.
description: The protocol used to communicate to the third-party network.
required: true
x-example: irc
- in: query
name: searchFields
type: string
description: |-
One or more custom fields to help identify the third party
One or more custom fields to help identify the third-party
location.
responses:
200:
@ -117,12 +117,12 @@ paths:
schema:
$ref: definitions/errors/error.yaml
tags:
- Third Party Lookup
- Third-party Lookup
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
summary: Retrieve the Matrix User ID of a corresponding third-party user.
description: |-
Retrieve a Matrix User ID linked to a user on the third party service, given
Retrieve a Matrix User ID linked to a user on the third-party service, given
a set of user parameters.
operationId: queryUserByProtocol
security:
@ -154,12 +154,12 @@ paths:
schema:
$ref: definitions/errors/error.yaml
tags:
- Third Party Lookup
- Third-party Lookup
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
Retrieve an array of third-party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
@ -174,7 +174,7 @@ paths:
responses:
200:
description: |-
All found third party locations.
All found third-party locations.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
@ -186,12 +186,12 @@ paths:
schema:
$ref: definitions/errors/error.yaml
tags:
- Third Party Lookup
- Third-party Lookup
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
summary: Reverse-lookup third-party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
Retrieve an array of third-party users from a Matrix User ID.
operationId: queryUserByID
security:
- accessToken: []
@ -205,7 +205,7 @@ paths:
responses:
200:
description: |-
An array of third party users.
An array of third-party users.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
@ -217,4 +217,4 @@ paths:
schema:
$ref: definitions/errors/error.yaml
tags:
- Third Party Lookup
- Third-party Lookup

18
data/api/client-server/third_party_membership.yaml
View file

@ -13,7 +13,7 @@
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Room Membership API for third party identifiers"
title: "Matrix Client-Server Room Membership API for third-party identifiers"
version: "1.0.0"
host: localhost:8008
schemes:
@ -33,9 +33,9 @@ paths:
description: |-
*Note that there are two forms of this API, which are documented separately.
This version of the API does not require that the inviter know the Matrix
identifier of the invitee, and instead relies on third party identifiers.
identifier of the invitee, and instead relies on third-party identifiers.
The homeserver uses an identity server to perform the mapping from
third party identifier to a Matrix identifier. The other is documented in the*
third-party identifier to a Matrix identifier. The other is documented in the*
[joining rooms section](/client-server-api/#post_matrixclientv3roomsroomidinvite).
This API invites a user to participate in a particular room.
@ -46,18 +46,18 @@ paths:
join that room.
If the identity server did know the Matrix user identifier for the
third party identifier, the homeserver will append a `m.room.member`
third-party identifier, the homeserver will append a `m.room.member`
event to the room.
If the identity server does not know a Matrix user identifier for the
passed third party identifier, the homeserver will issue an invitation
which can be accepted upon providing proof of ownership of the third
passed third-party identifier, the homeserver will issue an invitation
which can be accepted upon providing proof of ownership of the third-
party identifier. This is achieved by the identity server generating a
token, which it gives to the inviting homeserver. The homeserver will
add an `m.room.third_party_invite` event into the graph for the room,
containing that token.
When the invitee binds the invited third party identifier to a Matrix
When the invitee binds the invited third-party identifier to a Matrix
user ID, the identity server will give the user a list of pending
invitations, each containing:
@ -96,7 +96,7 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
id_access_token:
type: string
description: |-
@ -110,7 +110,7 @@ paths:
`email` (see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third party identifier.
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
responses:
200:

4
data/api/server-server/public_rooms.yaml
View file

@ -60,7 +60,7 @@ paths:
name: third_party_instance_id
type: string
description: |-
The specific third party network/protocol to request from the homeserver.
The specific third-party network/protocol to request from the homeserver.
Can only be used if `include_all_networks` is false.
x-example: "irc"
responses:
@ -131,7 +131,7 @@ paths:
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
example: "irc"
example: {

32
data/api/server-server/third_party_invite.yaml
View file

@ -14,7 +14,7 @@
swagger: '2.0'
info:
title: "Matrix Federation Third Party Invites API"
title: "Matrix Federation Third-party Invites API"
version: "1.0.0"
host: localhost:8448
schemes:
@ -29,7 +29,7 @@ securityDefinitions:
paths:
"/exchange_third_party_invite/{roomId}":
put:
summary: Request a server to auth a third party invite event
summary: Request a server to auth a third-party invite event
description: |-
The receiving server will verify the partial `m.room.member` event
given in the request body. If valid, the receiving server will issue
@ -42,7 +42,7 @@ paths:
- in: path
name: roomId
type: string
description: The room ID to exchange a third party invite in
description: The room ID to exchange a third-party invite in
required: true
x-example: "!abc123:matrix.org"
- in: body
@ -84,14 +84,14 @@ paths:
example: invite
third_party_invite:
type: object
description: The third party invite
title: Third Party Invite
description: The third-party invite
title: Third-party Invite
properties:
display_name:
type: string
description: |-
A name which can be displayed to represent the user instead of their
third party identifier.
third-party identifier.
example: "alice"
signed:
type: object
@ -203,11 +203,11 @@ paths:
"/3pid/onbind":
put:
summary: |-
Notifies the server that a third party identifier has been bound to one
Notifies the server that a third-party identifier has been bound to one
of its users.
description: |-
Used by identity servers to notify the homeserver that one of its users
has bound a third party identifier successfully, including any pending
has bound a third-party identifier successfully, including any pending
room invites the identity server has been made aware of.
operationId: onBindThirdPartyIdentifier
parameters:
@ -221,36 +221,36 @@ paths:
medium:
type: string
description: |-
The type of third party identifier. Currently only "email" is
The type of third-party identifier. Currently only "email" is
a possible value.
example: "email"
address:
type: string
description: |-
The third party identifier itself. For example, an email address.
The third-party identifier itself. For example, an email address.
example: "alice@example.com"
mxid:
type: string
description: The user that is now bound to the third party identifier.
description: The user that is now bound to the third-party identifier.
example: "@alice:matrix.org"
invites:
type: array
description: |-
A list of pending invites that the third party identifier has received.
A list of pending invites that the third-party identifier has received.
items:
type: object
title: Third Party Invite
title: Third-party Invite
properties:
medium:
type: string
description: |-
The type of third party invite issues. Currently only
The type of third-party invite issues. Currently only
"email" is used.
example: "email"
address:
type: string
description: |-
The third party identifier that received the invite.
The third-party identifier that received the invite.
example: "alice@example.com"
mxid:
type: string
@ -276,7 +276,7 @@ paths:
mxid:
type: string
description: |-
The user ID that has been bound to the third party
The user ID that has been bound to the third-party
identifier.
example: "@alice:matrix.org"
token:

2
data/event-schemas/schema/m.room.member.yaml
View file

@ -88,7 +88,7 @@ properties:
third_party_invite:
properties:
display_name:
description: A name which can be displayed to represent the user instead of their third party identifier
description: A name which can be displayed to represent the user instead of their third-party identifier
type: string
signed:
description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'

4
data/event-schemas/schema/m.room.third_party_invite.yaml
View file

@ -7,7 +7,7 @@ properties:
content:
properties:
display_name:
description: "A user-readable string which represents the user who has been invited. This should not contain the user's third party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third party ID."
description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID."
type: string
key_validity_url:
description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
@ -42,5 +42,5 @@ properties:
enum:
- m.room.third_party_invite
type: string
title: 'An invitation to a room issued to a third party identifier, rather than a matrix user ID.'
title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.'
type: object