diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index ec26cec8..b76ff570 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -297,7 +297,7 @@ specify parameter values. The flow for this method is as follows: 6. If the `m.identity_server` property is present, extract the `base_url` value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using - `/_matrix/identity/api/v1` as the endpoint to connect to. If the + `/_matrix/identity/v2` as the endpoint to connect to. If the `m.identity_server` property is present, but does not have a `base_url` value, then `FAIL_ERROR`. diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 60115306..cd915aaf 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -59,48 +59,48 @@ the keys `error` and `errcode` MUST always be present. Some standard error codes are below: -`M_NOT_FOUND` +`M_NOT_FOUND` The resource requested could not be located. -`M_MISSING_PARAMS` +`M_MISSING_PARAMS` The request was missing one or more parameters. -`M_INVALID_PARAM` +`M_INVALID_PARAM` The request contained one or more invalid parameters. -`M_SESSION_NOT_VALIDATED` +`M_SESSION_NOT_VALIDATED` The session has not been validated. -`M_NO_VALID_SESSION` +`M_NO_VALID_SESSION` A session could not be located for the given parameters. -`M_SESSION_EXPIRED` +`M_SESSION_EXPIRED` The session has expired and must be renewed. -`M_INVALID_EMAIL` +`M_INVALID_EMAIL` The email address provided was not valid. -`M_EMAIL_SEND_ERROR` +`M_EMAIL_SEND_ERROR` There was an error sending an email. Typically seen when attempting to verify ownership of a given email address. -`M_INVALID_ADDRESS` +`M_INVALID_ADDRESS` The provided third party address was not valid. -`M_SEND_ERROR` +`M_SEND_ERROR` There was an error sending a notification. Typically seen when attempting to verify ownership of a given third party address. -`M_UNRECOGNIZED` +`M_UNRECOGNIZED` The request contained an unrecognised value, such as an unknown token or medium. -`M_THREEPID_IN_USE` +`M_THREEPID_IN_USE` 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. -`M_UNKNOWN` +`M_UNKNOWN` An unknown error has occurred. ## Privacy @@ -114,22 +114,6 @@ Matrix user identity, but not in the other direction (i.e. one should not be able to get all 3PIDs associated with a Matrix user ID, or get all 3PIDs associated with a 3PID). -## Version 1 API deprecation - -As described on each of the version 1 endpoints, the v1 API is -deprecated in favour of the v2 API described here. The major difference, -with the exception of a few isolated cases, is that the v2 API requires -authentication to ensure the user has given permission for the identity -server to operate on their data. - -The v1 API is planned to be removed from the specification in a future -version. - -Clients SHOULD attempt the v2 endpoints first, and if they receive a -`404`, `400`, or similar error they should try the v1 endpoint or fail -the operation. Clients are strongly encouraged to warn the user of the -risks in using the v1 API, if they are planning on using it. - ## Web browser clients It is realistic to expect that some clients will be written to be run @@ -147,12 +131,9 @@ recommended CORS headers to be returned by servers on all requests are: ## Authentication -Most `v2` endpoints in the Identity Service API require authentication +Most endpoints in the Identity Service API require authentication in order to ensure that the requesting user has accepted all relevant -policies and is otherwise permitted to make the request. The `v1` API -(currently deprecated) does not require this authentication, however -using `v1` is strongly discouraged as it will be removed in a future -release. +policies and is otherwise permitted to make the request. Identity Servers use a scheme similar to the Client-Server API's concept of access tokens to authenticate users. The access tokens provided by an @@ -202,8 +183,6 @@ has just accepted are appended to `m.accepted_terms`. ## Status check -{{% http-api spec="identity" api="ping" %}} - {{% http-api spec="identity" api="v2_ping" %}} ## Key management @@ -217,23 +196,14 @@ The identity server may also keep track of some short-term public-private keypairs, which may have different usage and lifetime characteristics than the service's long-term keys. -{{% http-api spec="identity" api="pubkey" %}} - {{% http-api spec="identity" api="v2_pubkey" %}} ## Association lookup -{{% http-api spec="identity" api="lookup" %}} - {{% http-api spec="identity" api="v2_lookup" %}} ### Client behaviour -{{% boxes/note %}} -This section only covers the v2 lookup endpoint. The v1 endpoint is -described in isolation above. -{{% /boxes/note %}} - Prior to performing a lookup clients SHOULD make a request to the `/hash_details` endpoint to determine what algorithms the server supports (described in more detail below). The client then uses this @@ -244,11 +214,6 @@ Clients MUST support at least the `sha256` algorithm. ### Server behaviour -{{% boxes/note %}} -This section only covers the v2 lookup endpoint. The v1 endpoint is -described in isolation above. -{{% /boxes/note %}} - Servers, upon receipt of a `/lookup` request, will compare the query against known bindings it has, hashing the identifiers it knows about as needed to verify exact matches to the request. @@ -398,20 +363,14 @@ through without modification. ### Email associations -{{% http-api spec="identity" api="email_associations" %}} - {{% http-api spec="identity" api="v2_email_associations" %}} ### Phone number associations -{{% http-api spec="identity" api="phone_associations" %}} - {{% http-api spec="identity" api="v2_phone_associations" %}} ### General -{{% http-api spec="identity" api="associations" %}} - {{% http-api spec="identity" api="v2_associations" %}} ## Invitation storage @@ -427,8 +386,6 @@ the Matrix user's homeserver via the endpoint. The request MUST be signed with a long-term private key for the identity server. -{{% http-api spec="identity" api="store_invite" %}} - {{% http-api spec="identity" api="v2_store_invite" %}} ## Ephemeral invitation signing @@ -438,6 +395,4 @@ identity server offers some crypto functionality to help in accepting invitations. This is less secure than the client doing it itself, but may be useful where this isn't possible. -{{% http-api spec="identity" api="invitation_signing" %}} - {{% http-api spec="identity" api="v2_invitation_signing" %}} diff --git a/data/api/identity/associations.yaml b/data/api/identity/associations.yaml deleted file mode 100644 index f2d09af1..00000000 --- a/data/api/identity/associations.yaml +++ /dev/null @@ -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. diff --git a/data/api/identity/email_associations.yaml b/data/api/identity/email_associations.yaml deleted file mode 100644 index 6aa7bf4a..00000000 --- a/data/api/identity/email_associations.yaml +++ /dev/null @@ -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. diff --git a/data/api/identity/invitation_signing.yaml b/data/api/identity/invitation_signing.yaml deleted file mode 100644 index a3d215f2..00000000 --- a/data/api/identity/invitation_signing.yaml +++ /dev/null @@ -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" diff --git a/data/api/identity/lookup.yaml b/data/api/identity/lookup.yaml deleted file mode 100644 index 6163807e..00000000 --- a/data/api/identity/lookup.yaml +++ /dev/null @@ -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" diff --git a/data/api/identity/phone_associations.yaml b/data/api/identity/phone_associations.yaml deleted file mode 100644 index 53d4132d..00000000 --- a/data/api/identity/phone_associations.yaml +++ /dev/null @@ -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. diff --git a/data/api/identity/ping.yaml b/data/api/identity/ping.yaml deleted file mode 100644 index d7249a77..00000000 --- a/data/api/identity/ping.yaml +++ /dev/null @@ -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 diff --git a/data/api/identity/pubkey.yaml b/data/api/identity/pubkey.yaml deleted file mode 100644 index a585e7ec..00000000 --- a/data/api/identity/pubkey.yaml +++ /dev/null @@ -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'] diff --git a/data/api/identity/store_invite.yaml b/data/api/identity/store_invite.yaml deleted file mode 100644 index 20e40852..00000000 --- a/data/api/identity/store_invite.yaml +++ /dev/null @@ -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"