matrix-spec-proposals/api/identity/v2_terms.yaml

# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
  title: "Matrix Identity Service Terms of Service API"
  version: "2.0.0"
host: localhost:8090
schemes:
  - https
basePath: /_matrix/identity/v2
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/terms":
    get:
      summary: Gets the terms of service offered by the server.
      description: |-
        Gets all the terms of service offered by the server. The client is expected
        to filter through the terms to determine which terms need acceptance from the
        user. Note that this endpoint does not require authentication.        
      operationId: getTerms
      parameters: []
      responses:
        200:
          description: |-
                        The terms of service offered by the server.
          examples:
            application/json: {
              "policies": {
                "terms_of_service": {
                  "version": "2.0",
                  "en": {
                    "name": "Terms of Service",
                    "url": "https://example.org/somewhere/terms-2.0-en.html"
                  },
                  "fr": {
                    "name": "Conditions d'utilisation",
                    "url": "https://example.org/somewhere/terms-2.0-fr.html"
                  }
                },
                "privacy_policy": {
                  "version": "1.2",
                  "en": {
                    "name": "Privacy Policy",
                    "url": "https://example.org/somewhere/privacy-1.2-en.html"
                  },
                  "fr": {
                    "name": "Politique de confidentialité",
                    "url": "https://example.org/somewhere/privacy-1.2-fr.html"
                  }
                }
              }
            }
          schema:
            type: object
            properties:
              policies:
                type: object
                title: Policy Map
                description: |-
                  The policies the server offers. Mapped from arbitrary ID (unused in
                  this version of the specification) to a Policy Object.                  
                additionalProperties:
                  type: object
                  title: Policy Object
                  description: |-
                    The policy. Includes a map of language (ISO 639-2) to language-specific
                    policy information.                    
                  properties:
                    version:
                      type: string
                      description: |-
                        The version for the policy. There are no requirements on what this
                        might be and could be "alpha", semantically versioned, or arbitrary.                        
                  required: ['version']
                  # TODO: TravisR - Make this render
                  additionalProperties:
                    type: object
                    title: Internationalised Policy
                    description: |-
                                            The policy information for the specified language.
                    properties:
                      name:
                        type: string
                        description: The translated name of the policy.
                      url:
                        type: string
                        description: |-
                          The URL, which should include the policy ID, version, and language
                          in it, to be presented to the user as the policy. URLs should have
                          all three criteria to avoid conflicts when the policy is updated
                          in the future: for example, if this was "https://example.org/terms.html"
                          then the server would be unable to update it because the client would
                          have already added that URL to the ``m.accepted_terms`` collection.                          
                    required: ['name', 'url']
            required: ['policies']
    post:
      summary: Indicates acceptance of terms to the server.
      description: |-
        Called by a client to indicate that the user has accepted/agreed to the included
        set of URLs. Servers MUST NOT assume that the client will be sending all previously
        accepted URLs and should therefore append the provided URLs to what the server
        already knows has been accepted.

        Clients MUST provide the URL of the policy in the language that was presented
        to the user. Servers SHOULD consider acceptance of any one language's URL as
        acceptance for all other languages of that policy.

        The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client
        may not be accepting all terms at once.        
      operationId: agreeToTerms
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_accepts:
                type: array
                items:
                  type: string
                description: The URLs the user is accepting in this request.
                example: "https://example.org/somewhere/terms-2.0-en.html"
            required: ['user_accepts']
      responses:
        200:
          description: |-
                        The server has considered the user as having accepted the provided URLs.
          examples:
            application/json: {}
          schema:
            type: object