async-matrix 0.1.3 → 1.1.0

data/data/matrix-spec/api/client-server/sso_login_redirect.yaml

@@ -0,0 +1,135 @@
+# Copyright 2019 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server SSO Login API
+  version: 1.0.0
+paths:
+  /login/sso/redirect:
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Redirect the user's browser to the SSO interface.
+      description: |-
+        A web-based Matrix client should instruct the user's browser to
+        navigate to this endpoint in order to log in via SSO.
+
+        The server MUST respond with an HTTP redirect to the SSO interface,
+        or present a page which lets the user select an IdP to continue
+        with in the event multiple are supported by the server.
+      operationId: redirectToSSO
+      parameters:
+        - in: query
+          name: redirectUrl
+          description: |-
+            URI to which the user will be redirected after the homeserver has
+            authenticated the user with SSO.
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
+      responses:
+        "302":
+          description: A redirect to the SSO interface.
+          headers:
+            Location:
+              schema:
+                type: string
+      tags:
+        - Session management
+  "/login/sso/redirect/{idpId}":
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Redirect the user's browser to the SSO interface for an IdP.
+      description: |-
+        This endpoint is the same as `/login/sso/redirect`, though with an
+        IdP ID from the original `identity_providers` array to inform the
+        server of which IdP the client/user would like to continue with.
+
+        The server MUST respond with an HTTP redirect to the SSO interface
+        for that IdP.
+      operationId: redirectToIdP
+      parameters:
+        - in: path
+          name: idpId
+          required: true
+          description: |-
+            The `id` of the IdP from the `m.login.sso` `identity_providers`
+            array denoting the user's selection.
+          schema:
+            type: string
+        - in: query
+          name: redirectUrl
+          description: |-
+            URI to which the user will be redirected after the homeserver has
+            authenticated the user with SSO.
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
+      responses:
+        "302":
+          description: A redirect to the SSO interface.
+          headers:
+            Location:
+              schema:
+                type: string
+        "404":
+          description: |-
+            The IdP ID was not recognized by the server. The server is encouraged
+            to provide a user-friendly page explaining the error given the user
+            will be navigated to it.
+      tags:
+        - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3

data/data/matrix-spec/api/client-server/support.yaml

@@ -0,0 +1,142 @@
+# Copyright 2024 Kévin Commaille
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Support Discovery API
+  version: 1.0.0
+paths:
+  /matrix/support:
+    get:
+      summary: Gets homeserver contacts and support details.
+      description: |-
+        Gets server admin contact and support page of the domain.
+
+        {{% boxes/note %}}
+        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/support`.
+        {{% /boxes/note %}}
+
+        Note that this endpoint is not necessarily handled by the homeserver.
+        It may be served by another webserver, used for discovering support
+        information for the homeserver.
+      operationId: getWellknownSupport
+      x-addedInMatrixVersion: "1.10"
+      responses:
+        "200":
+          description: Server support information.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  contacts:
+                    type: array
+                    description: |-
+                      Ways to contact the server administrator.
+
+                      At least one of `contacts` or `support_page` is required.
+                      If only `contacts` is set, it must contain at least one
+                      item.
+                    items:
+                      type: object
+                      title: Contact
+                      description: A way to contact the server administrator.
+                      properties:
+                        matrix_id:
+                          type: string
+                          format: mx-user-id
+                          pattern: "^@"
+                          description: |-
+                            A [Matrix User ID](/appendices/#user-identifiers)
+                            representing the administrator.
+
+                            It could be an account registered on a different
+                            homeserver so the administrator can be contacted
+                            when the homeserver is down.
+
+                            At least one of `matrix_id` or `email_address` is
+                            required.
+                        email_address:
+                          type: string
+                          format: email
+                          description: |-
+                            An email address to reach the administrator.
+
+                            At least one of `matrix_id` or `email_address` is
+                            required.
+                        role:
+                          type: string
+                          enum:
+                            - "m.role.admin"
+                            - "m.role.security"
+                          description: |-
+                            An informal description of what the contact methods
+                            are used for.
+
+                            `m.role.admin` is a catch-all role for any queries
+                            and `m.role.security` is intended for sensitive
+                            requests.
+
+                            Unspecified roles are permitted through the use of
+                            [Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar).
+                      required:
+                        - role
+                      example: {
+                        "matrix_id": "@admin:example.org",
+                        "email_address": "admin@example.org",
+                        "role": "m.role.admin"
+                      }
+                  support_page:
+                    type: string
+                    format: uri
+                    description: |-
+                      The URL of a page to give users help specific to the
+                      homeserver, like extra login/registration steps.
+
+                      At least one of `contacts` or `support_page` is required.
+                    example: "https://example.org/support.html"
+              examples:
+                response:
+                  value:
+                    {
+                      "contacts": [
+                        {
+                          "matrix_id": "@admin:example.org",
+                          "email_address": "admin@example.org",
+                          "role": "m.role.admin"
+                        },
+                        {
+                          "email_address": "security@example.org",
+                          "role": "m.role.security"
+                        }
+                      ],
+                      "support_page": "https://example.org/support.html"
+                    }
+        "404":
+          description: No server support information available.
+      tags:
+        - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /.well-known