# Copyright 2019-2020 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Client-Server Key Backup API
  version: 1.0.0
paths:
  /room_keys/version:
    post:
      x-addedInMatrixVersion: "1.1"
      summary: Create a new backup.
      description: Creates a new backup.
      operationId: postRoomKeysVersion
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                algorithm:
                  description: The algorithm used for storing backups.
                  type: string
                  enum:
                    - m.megolm_backup.v1.curve25519-aes-sha2
                  example: m.megolm_backup.v1.curve25519-aes-sha2
                auth_data:
                  description: |-
                    Algorithm-dependent data. See the documentation for the backup
                    algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                    expected format of the data.
                  type: object
                  example:
                    public_key: abcdefg
                    signatures:
                      "@alice:example.org":
                        ed25519:deviceid: signature
              required:
                - algorithm
                - auth_data
        description: The backup configuration.
        required: true
      responses:
        "200":
          description: The version id of the new backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: The backup version. This is an opaque string.
                    example: "1"
                required:
                  - version
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Get information about the latest backup version.
      description: Get information about the latest backup version.
      operationId: getRoomKeysVersionCurrent
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      responses:
        "200":
          description: The information about the backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  algorithm:
                    type: string
                    description: The algorithm used for storing backups.
                    enum:
                      - m.megolm_backup.v1.curve25519-aes-sha2
                    example: m.megolm_backup.v1.curve25519-aes-sha2
                  auth_data:
                    description: |-
                      Algorithm-dependent data. See the documentation for the backup
                      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                      expected format of the data.
                    type: object
                    example:
                      public_key: abcdefg
                      signatures:
                        "@alice:example.org":
                          ed25519:deviceid: signature
                  count:
                    description: The number of keys stored in the backup.
                    type: integer
                    example: 42
                  etag:
                    description: |-
                      An opaque string representing stored keys in the backup.
                      Clients can compare it with the `etag` value they received
                      in the request of their last key storage request.  If not
                      equal, another client has modified the backup.
                    type: string
                    example: anopaquestring
                  version:
                    type: string
                    description: The backup version.
                    example: "1"
                required:
                  - algorithm
                  - auth_data
                  - count
                  - etag
                  - version
        "404":
          description: No backup exists.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "No current backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
  "/room_keys/version/{version}":
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Get information about an existing backup.
      description: Get information about an existing backup.
      operationId: getRoomKeysVersion
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: version
          description: |-
            The backup version to get, as returned in the `version` parameter
            of the response in
            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
            or this endpoint.
          required: true
          example: "1"
          schema:
            type: string
      responses:
        "200":
          description: The information about the requested backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  algorithm:
                    type: string
                    description: The algorithm used for storing backups.
                    enum:
                      - m.megolm_backup.v1.curve25519-aes-sha2
                    example: m.megolm_backup.v1.curve25519-aes-sha2
                  auth_data:
                    description: |-
                      Algorithm-dependent data. See the documentation for the backup
                      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                      expected format of the data.
                    type: object
                    example:
                      public_key: abcdefg
                      signatures:
                        "@alice:example.org":
                          ed25519:deviceid: signature
                  count:
                    description: The number of keys stored in the backup.
                    type: integer
                    example: 42
                  etag:
                    description: |-
                      An opaque string representing stored keys in the backup.
                      Clients can compare it with the `etag` value they received
                      in the request of their last key storage request.  If not
                      equal, another client has modified the backup.
                    type: string
                    example: anopaquestring
                  version:
                    type: string
                    description: The backup version.
                    example: "1"
                required:
                  - algorithm
                  - auth_data
                  - count
                  - etag
                  - version
        "404":
          description: The backup specified does not exist.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    put:
      x-addedInMatrixVersion: "1.1"
      summary: Update information about an existing backup.
      description: Update information about an existing backup.  Only `auth_data` can
        be modified.
      operationId: putRoomKeysVersion
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: version
          description: |-
            The backup version to update, as returned in the `version`
            parameter in the response of
            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
            or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
          required: true
          example: "1"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                algorithm:
                  description: |-
                    The algorithm used for storing backups.  Must be the same as
                    the algorithm currently used by the backup.
                  type: string
                  enum:
                    - m.megolm_backup.v1.curve25519-aes-sha2
                  example: m.megolm_backup.v1.curve25519-aes-sha2
                auth_data:
                  description: |-
                    Algorithm-dependent data. See the documentation for the backup
                    algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                    expected format of the data.
                  type: object
                  example:
                    public_key: abcdefg
                    signatures:
                      "@alice:example.org":
                        ed25519:deviceid: signature
                version:
                  description: |-
                    The backup version.  If present, must be the same as the
                    version in the path parameter.
                  type: string
                  example: "1"
              required:
                - algorithm
                - auth_data
        description: The backup configuration
        required: true
      responses:
        "200":
          description: The update succeeded.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "400":
          description: |-
            A parameter was incorrect.  For example, the `algorithm` does not
            match the current backup algorithm, or the `version` in the body
            does not match the `version` in the path.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_INVALID_PARAM",
                    "error": "Algorithm does not match"
                  }
        "404":
          description: The backup specified does not exist.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    delete:
      x-addedInMatrixVersion: "1.1"
      summary: Delete an existing key backup.
      description: |-
        Delete an existing key backup. Both the information about the backup,
        as well as all key data related to the backup will be deleted.
      operationId: deleteRoomKeysVersion
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: version
          description: |-
            The backup version to delete, as returned in the `version`
            parameter in the response of
            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
            or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
          required: true
          example: "1"
          schema:
            type: string
      responses:
        "200":
          description: |-
            The delete succeeded, or the specified backup was previously
            deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        "404":
          description: |-
            The backup specified does not exist. If the backup was previously
            deleted, the call should succeed rather than returning an error.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
  "/room_keys/keys/{roomId}/{sessionId}":
    put:
      x-addedInMatrixVersion: "1.1"
      summary: Store a key in the backup.
      description: Store a key in the backup.
      operationId: putRoomKeyBySessionId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup in which to store the key. Must be the current backup.
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the key is for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
        - in: path
          name: sessionId
          description: The ID of the megolm session that the key is for.
          required: true
          example: sessionid
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: definitions/key_backup_data.yaml
        description: The key data.
        required: true
      responses:
        "200":
          description: The update succeeded.
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "403":
          description: |-
            The version specified does not match the current backup version.
            The current version will be included in the `current_version`
            field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
                    "error": "Wrong backup version.",
                    "current_version": "42"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Retrieve a key from the backup.
      description: Retrieve a key from the backup.
      operationId: getRoomKeyBySessionId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to retrieve the key.
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the requested key is for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
        - in: path
          name: sessionId
          description: The ID of the megolm session whose key is requested.
          required: true
          example: sessionid
          schema:
            type: string
      responses:
        "200":
          description: The key data
          content:
            application/json:
              schema:
                $ref: definitions/key_backup_data.yaml
        "404":
          description: The key or backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Key not found."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    delete:
      x-addedInMatrixVersion: "1.1"
      summary: Delete a key from the backup.
      description: Delete a key from the backup.
      operationId: deleteRoomKeyBySessionId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to delete the key
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the specified key is for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
        - in: path
          name: sessionId
          description: The ID of the megolm session whose key is to be deleted.
          required: true
          example: sessionid
          schema:
            type: string
      responses:
        "200":
          description: The update succeeded
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
  "/room_keys/keys/{roomId}":
    put:
      x-addedInMatrixVersion: "1.1"
      summary: Store several keys in the backup for a given room.
      description: Store several keys in the backup for a given room.
      operationId: putRoomKeysByRoomId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup in which to store the keys. Must be the current backup.
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the keys are for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: definitions/room_key_backup.yaml
        description: The backup data
        required: true
      responses:
        "200":
          description: The update succeeded
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "403":
          description: |-
            The version specified does not match the current backup version.
            The current version will be included in the `current_version`
            field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
                    "error": "Wrong backup version.",
                    "current_version": "42"
                  }
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Retrieve the keys from the backup for a given room.
      description: Retrieve the keys from the backup for a given room.
      operationId: getRoomKeysByRoomId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to retrieve the key.
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the requested key is for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
      responses:
        "200":
          description: |-
            The key data.  If no keys are found, then an object with an empty
            `sessions` property will be returned (`{"sessions": {}}`).
          content:
            application/json:
              schema:
                type: object
                $ref: definitions/room_key_backup.yaml
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    delete:
      x-addedInMatrixVersion: "1.1"
      summary: Delete the keys from the backup for a given room.
      description: Delete the keys from the backup for a given room.
      operationId: deleteRoomKeysByRoomId
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to delete the key.
          required: true
          example: "1"
          schema:
            type: string
        - in: path
          name: roomId
          description: The ID of the room that the specified key is for.
          required: true
          example: "!roomid:example.org"
          schema:
            type: string
      responses:
        "200":
          description: The update succeeded
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
  /room_keys/keys:
    put:
      x-addedInMatrixVersion: "1.1"
      summary: Store several keys in the backup.
      description: Store several keys in the backup.
      operationId: putRoomKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup in which to store the keys. Must be the current backup.
          required: true
          example: "1"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rooms:
                  type: object
                  description: A map of room IDs to room key backup data.
                  patternProperties:
                    "^!":
                      x-pattern-format: mx-room-id
                      allOf:
                        - $ref: definitions/room_key_backup.yaml
                  example:
                    "!room:example.org":
                      sessions:
                        sessionid1:
                          first_message_index: 1
                          forwarded_count: 0
                          is_verified: true
                          session_data:
                            ephemeral: base64+ephemeral+key
                            ciphertext: base64+ciphertext+of+JSON+data
                            mac: base64+mac+of+ciphertext
              required:
                - rooms
        description: The backup data.
        required: true
      responses:
        "200":
          description: The update succeeded
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "403":
          description: |-
            The version specified does not match the current backup version.
            The current version will be included in the `current_version`
            field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
                    "error": "Wrong backup version.",
                    "current_version": "42"
                  }
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Retrieve the keys from the backup.
      description: Retrieve the keys from the backup.
      operationId: getRoomKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to retrieve the keys.
          required: true
          example: "1"
          schema:
            type: string
      responses:
        "200":
          description: |-
            The key data.  If no keys are found, then an object with an empty
            `rooms` property will be returned (`{"rooms": {}}`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: object
                    description: A map of room IDs to room key backup data.
                    patternProperties:
                      "^!":
                        x-pattern-format: mx-room-id
                        allOf:
                          - $ref: definitions/room_key_backup.yaml
                    example:
                      "!room:example.org":
                        sessions:
                          sessionid1:
                            first_message_index: 1
                            forwarded_count: 0
                            is_verified: true
                            session_data:
                              ephemeral: base64+ephemeral+key
                              ciphertext: base64+ciphertext+of+JSON+data
                              mac: base64+mac+of+ciphertext
                required:
                  - rooms
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
    delete:
      x-addedInMatrixVersion: "1.1"
      summary: Delete the keys from the backup.
      description: Delete the keys from the backup.
      operationId: deleteRoomKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: version
          description: The backup from which to delete the key
          required: true
          example: "1"
          schema:
            type: string
      responses:
        "200":
          description: The update succeeded
          content:
            application/json:
              schema:
                type: object
                title: RoomKeysUpdateResponse
                properties:
                  etag:
                    description: |-
                      The new etag value representing stored keys in the backup.
                      See `GET /room_keys/version/{version}` for more details.
                    type: string
                    example: abcdefg
                  count:
                    description: The number of keys stored in the backup
                    type: integer
                    example: 10
                required:
                  - etag
                  - count
        "404":
          description: The backup was not found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unknown backup version"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - End-to-end encryption
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer
