Fix security schemes in OpenAPI definitions (#1772)

changelogs/application_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/client_server/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/identity_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/server_server/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

data/api/application-service/definitions/security.yaml

@@ -13,7 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 homeserverAccessToken:
-  type: apiKey
+  type: http
-  name: Authorization
+  scheme: bearer
-  in: header
   description: The `Bearer` `hs_token` provided by the application service's registration.

data/api/application-service/ping.yaml

@@ -69,4 +69,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/protocols.yaml

@@ -339,4 +339,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/query_room.yaml

@@ -103,4 +103,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/query_user.yaml

@@ -100,4 +100,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/transactions.yaml

@@ -88,4 +88,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/client-server/account-data.yaml

@@ -26,7 +26,8 @@ paths:
         [/sync](#get_matrixclientv3sync).
       operationId: setAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -117,7 +118,8 @@ paths:
         that set the account data.
       operationId: getAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -186,7 +188,8 @@ paths:
         clients in the per-room entries via [/sync](#get_matrixclientv3sync).
       operationId: setAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -285,7 +288,8 @@ paths:
         visible to the user that set the account data.
       operationId: getAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -379,4 +383,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/admin.yaml

@@ -27,7 +27,8 @@ paths:
         specified in this document.
       operationId: getWhoIs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/administrative_contact.yaml

@@ -31,7 +31,8 @@ paths:
         identifiers that it will accept to reset the user's account password.
       operationId: getAccount3PIDs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The lookup was successful.
@@ -101,7 +102,8 @@ paths:
       operationId: post3PIDs
       deprecated: true
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -201,7 +203,8 @@ paths:
         already been added to another user's account on the homeserver.
       operationId: add3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -263,7 +266,8 @@ paths:
         Homeservers should track successful binds so they can be unbound later.
       operationId: bind3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -324,7 +328,8 @@ paths:
         identity server instead.
       operationId: delete3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -393,7 +398,8 @@ paths:
         identity server instead.
       operationId: unbind3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -584,4 +590,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/appservice_ping.yaml

@@ -57,8 +57,8 @@ paths:
                   example: mautrix-go_1683636478256400935_123
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
+        - appserviceAccessTokenQuery: []
-        - accessToken: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The ping was successful.
@@ -177,6 +177,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
+    appserviceAccessTokenQuery:
-    # server API, however this expects an access token for an application service.
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
-    $ref: definitions/security.yaml
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer

data/api/client-server/appservice_room_directory.yaml

@@ -67,8 +67,8 @@ paths:
                 - visibility
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
+        - appserviceAccessTokenQuery: []
-        - accessToken: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The room's directory visibility has been updated.
@@ -95,6 +95,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
+    appserviceAccessTokenQuery:
-    # server API, however this expects an access token for an application service.
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
-    $ref: definitions/security.yaml
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer

data/api/client-server/banning.yaml

@@ -27,7 +27,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: ban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -96,7 +97,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: unban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -169,4 +171,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/capabilities.yaml

@@ -24,7 +24,8 @@ paths:
         and other relevant capabilities.
       operationId: getCapabilities
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The capabilities of the server.
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/content-repo.yaml

@@ -22,7 +22,8 @@ paths:
       summary: Upload some content to the content repository.
       operationId: uploadContent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: header
           name: Content-Type
@@ -234,7 +235,8 @@ paths:
       operationId: createContent
       x-addedInMatrixVersion: "1.7"
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       # empty json object
       responses:
         "200":
@@ -782,7 +784,8 @@ paths:
         being shared should also not be shared with the homeserver.
       operationId: getUrlPreview
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: url
@@ -857,7 +860,8 @@ paths:
         than is advertised by the server on this endpoint.
       operationId: getConfig
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The public content repository configuration for the matrix server.
@@ -900,4 +904,7 @@ servers:
         default: /_matrix
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/create_room.yaml

@@ -64,7 +64,8 @@ paths:
         `creation_content`.
       operationId: createRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -290,4 +291,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/cross_signing.yaml

@@ -26,7 +26,8 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
       operationId: uploadCrossSigningKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -155,7 +156,8 @@ paths:
         property, which contains the new signature(s) to add.
       operationId: uploadCrossSigningSignatures
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -262,4 +264,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/definitions/security.yaml

@@ -11,8 +11,36 @@
 # 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.
-accessToken:
+accessTokenQuery:
   type: apiKey
-  description: The access_token returned by a call to `/login` or `/register`
+  description: |-
+    The `access_token` returned by a call to `/login` or `/register`, as a query
+    parameter.
+
+    It can also be the `as_token` of an application service.
   name: access_token
   in: query
+accessTokenBearer:
+  type: http
+  description: |-
+    The `access_token` returned by a call to `/login` or `/register`, using the
+    `Authorization: Bearer` header.
+
+    It can also be the `as_token` of an application service.
+    
+    This is the preferred method.
+  scheme: bearer
+appserviceAccessTokenQuery:
+  type: apiKey
+  description: |-
+    The `as_token` of an application service, as a query parameter.
+  name: access_token
+  in: query
+appserviceAccessTokenBearer:
+  type: http
+  description: |-
+    The `as_token` of an application service, using the `Authorization: Bearer`
+    header.
+    
+    This is the preferred method.
+  scheme: bearer

data/api/client-server/device_management.yaml

@@ -22,7 +22,8 @@ paths:
       description: Gets information about all devices for the current user.
       operationId: getDevices
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: Device information
@@ -58,7 +59,8 @@ paths:
       description: Gets information on a single device, by device id.
       operationId: getDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -93,7 +95,8 @@ paths:
       description: Updates the metadata on the given device.
       operationId: updateDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -140,7 +143,8 @@ paths:
         Deletes the given device, and invalidates any access token associated with it.
       operationId: deleteDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -191,7 +195,8 @@ paths:
         Deletes the given devices, and invalidates any access token associated with them.
       operationId: deleteDevices
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -250,4 +255,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/directory.yaml

@@ -21,7 +21,8 @@ paths:
       summary: Create a new mapping from room alias to room ID.
       operationId: setRoomAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomAlias
@@ -172,7 +173,8 @@ paths:
         have permission to update the `m.room.canonical_alias` event.
       operationId: deleteRoomAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomAlias
@@ -229,7 +231,8 @@ paths:
         state event.
       operationId: getLocalAliases
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -309,4 +312,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/event_context.yaml

@@ -28,7 +28,8 @@ paths:
         [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getEventContext
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -154,4 +155,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/filter.yaml

@@ -25,7 +25,8 @@ paths:
         restrict which events are returned to the client.
       operationId: defineFilter
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -119,7 +120,8 @@ paths:
       summary: Download a filter
       operationId: getFilter
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -214,4 +216,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/inviting.yaml

@@ -38,7 +38,8 @@ paths:
         `m.room.member` event to the room.
       operationId: inviteUser
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -136,4 +137,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/joining.yaml

@@ -33,7 +33,8 @@ paths:
         and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
       operationId: joinRoomById
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -126,7 +127,8 @@ paths:
         and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
       operationId: joinRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomIdOrAlias
@@ -229,4 +231,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/key_backup.yaml

@@ -23,7 +23,8 @@ paths:
       description: Creates a new backup.
       operationId: postRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -80,7 +81,8 @@ paths:
       description: Get information about the latest backup version.
       operationId: getRoomKeysVersionCurrent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The information about the backup.
@@ -155,7 +157,8 @@ paths:
       description: Get information about an existing backup.
       operationId: getRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -242,7 +245,8 @@ paths:
         be modified.
       operationId: putRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -344,7 +348,8 @@ paths:
         as well as all key data related to the backup will be deleted.
       operationId: deleteRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -396,7 +401,8 @@ paths:
       description: Store a key in the backup.
       operationId: putRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -478,7 +484,8 @@ paths:
       description: Retrieve a key from the backup.
       operationId: getRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -534,7 +541,8 @@ paths:
       description: Delete a key from the backup.
       operationId: deleteRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -606,7 +614,8 @@ paths:
       description: Store several keys in the backup for a given room.
       operationId: putRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -693,7 +702,8 @@ paths:
       description: Retrieve the keys from the backup for a given room.
       operationId: getRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -745,7 +755,8 @@ paths:
       description: Delete the keys from the backup for a given room.
       operationId: deleteRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -810,7 +821,8 @@ paths:
       description: Store several keys in the backup.
       operationId: putRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -910,7 +922,8 @@ paths:
       description: Retrieve the keys from the backup.
       operationId: getRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -974,7 +987,8 @@ paths:
       description: Delete the keys from the backup.
       operationId: deleteRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -1039,4 +1053,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/keys.yaml

@@ -24,7 +24,8 @@ paths:
       description: Publishes end-to-end encryption keys for the device.
       operationId: uploadKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -120,7 +121,8 @@ paths:
       description: Returns the current devices and identity keys for the given users.
       operationId: queryKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -283,7 +285,8 @@ paths:
       description: Claims one-time keys for use in pre-key messages.
       operationId: claimKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -383,7 +386,8 @@ paths:
           identity keys, between `from` and `to`.
       operationId: getKeysChanges
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -453,4 +457,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/kicking.yaml

@@ -29,7 +29,8 @@ paths:
         the target member's state by making a request to `/rooms/<room id>/state/m.room.member/<user id>`.
       operationId: kick
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -103,4 +104,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/knocking.yaml

@@ -38,7 +38,8 @@ paths:
         [`/sync`](/client-server-api/#get_matrixclientv3sync) API.
       operationId: knockRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomIdOrAlias
@@ -144,4 +145,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/leaving.yaml

@@ -33,7 +33,8 @@ paths:
         they were previously allowed to see.
       operationId: leaveRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -91,7 +92,8 @@ paths:
         before calling this API.
       operationId: forgetRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -144,4 +146,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/list_joined_rooms.yaml

@@ -22,7 +22,8 @@ paths:
       description: This API returns a list of the user's current rooms.
       operationId: getJoinedRooms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: A list of the rooms the user is in.
@@ -61,4 +62,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/list_public_rooms.yaml

@@ -74,7 +74,8 @@ paths:
         the room creator or a server administrator.
       operationId: setRoomVisibilityOnDirectory
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -175,7 +176,8 @@ paths:
         of joined members, with the largest rooms first.
       operationId: queryPublicRooms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: server
@@ -267,3 +269,9 @@ servers:
         default: localhost:8008
       basePath:
         default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login.yaml

@@ -284,4 +284,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login_token.yaml

@@ -53,7 +53,8 @@ paths:
       operationId: generateLoginToken
       x-addedInMatrixVersion: "1.7"
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -131,4 +132,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/logout.yaml

@@ -25,7 +25,8 @@ paths:
         [Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
       operationId: logout
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The access token used in the request was successfully invalidated.
@@ -53,7 +54,8 @@ paths:
         this way.
       operationId: logout_all
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The user's access tokens were successfully invalidated.
@@ -78,4 +80,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/message_pagination.yaml

@@ -27,7 +27,8 @@ paths:
         [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getRoomEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -185,4 +186,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/notifications.yaml

@@ -24,7 +24,8 @@ paths:
         user has been, or would have been notified about.
       operationId: getNotifications
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -145,4 +146,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/old_sync.yaml

@@ -29,7 +29,8 @@ paths:
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: getEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -99,7 +100,8 @@ paths:
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: initialSync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: limit
@@ -325,7 +327,8 @@ paths:
         or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
       operationId: getOneEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: eventId
@@ -366,4 +369,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/openid.yaml

@@ -30,7 +30,8 @@ paths:
         example.
       operationId: requestOpenIdToken
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -91,4 +92,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/peeking_events.yaml

@@ -34,7 +34,8 @@ paths:
         yet known.
       operationId: peekEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -114,4 +115,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/presence.yaml

@@ -26,7 +26,8 @@ paths:
         presence state of another user.
       operationId: setPresence
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -82,7 +83,8 @@ paths:
       description: Get the given user's presence state.
       operationId: getPresence
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -161,4 +163,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/profile.yaml

@@ -24,7 +24,8 @@ paths:
         set this user's display name, e.g. you need to have their `access_token`.
       operationId: setDisplayName
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -109,7 +110,8 @@ paths:
         set this user's avatar URL, e.g. you need to have their `access_token`.
       operationId: setAvatarUrl
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -269,4 +271,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/pusher.yaml

@@ -23,7 +23,8 @@ paths:
       description: Gets all currently active pushers for the authenticated user.
       operationId: getPushers
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The pushers for this user.
@@ -136,7 +137,8 @@ paths:
         user is deleted.
       operationId: postPusher
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -288,4 +290,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/pushrules.yaml

@@ -26,7 +26,8 @@ paths:
         specified key e.g. the `global` key.
       operationId: getPushRules
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: All the push rulesets for this user.
@@ -242,7 +243,8 @@ paths:
       description: Retrieve a single specified push rule.
       operationId: getPushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -313,7 +315,8 @@ paths:
       description: This endpoint removes the push rule defined in the path.
       operationId: deletePushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -389,7 +392,8 @@ paths:
         When creating push rules, they MUST be enabled by default.
       operationId: setPushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -527,7 +531,8 @@ paths:
       description: This endpoint gets whether the specified push rule is enabled.
       operationId: isPushRuleEnabled
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -598,7 +603,8 @@ paths:
         push rule.
       operationId: setPushRuleEnabled
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -676,7 +682,8 @@ paths:
       description: This endpoint get the actions for the specified push rule.
       operationId: getPushRuleActions
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -756,7 +763,8 @@ paths:
         This can be used to change the actions of builtin rules.
       operationId: setPushRuleActions
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -849,4 +857,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/read_markers.yaml

@@ -25,7 +25,8 @@ paths:
         the read receipt's location.
       operationId: setReadMarker
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -96,4 +97,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/receipts.yaml

@@ -25,7 +25,8 @@ paths:
         specified.
       operationId: postReceipt
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -132,4 +133,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/redaction.yaml

@@ -33,7 +33,8 @@ paths:
         Server administrators may redact events sent by users on their server.
       operationId: redactEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -103,4 +104,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/registration.yaml

@@ -387,7 +387,8 @@ paths:
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       operationId: changePassword
       requestBody:
         content:
@@ -591,7 +592,8 @@ paths:
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       operationId: deactivateAccount
       requestBody:
         content:
@@ -757,3 +759,9 @@ servers:
         default: localhost:8008
       basePath:
         default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/relations.yaml

@@ -31,7 +31,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -88,7 +89,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEventsWithRelType
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -149,7 +151,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEventsWithRelTypeAndEventType
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -217,7 +220,10 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
   parameters:
     roomId:
       in: path

data/api/client-server/report_content.yaml

@@ -65,7 +65,8 @@ paths:
                   description: The reason the content is being reported. May be blank.
         required: true
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       x-changedInMatrixVersion:
         1.8: |
           This endpoint now requires the user to be joined to the room.
@@ -112,4 +113,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/room_event_by_timestamp.yaml

@@ -46,7 +46,8 @@ paths:
         found in that direction is outside of the expected range.
       operationId: getEventByTimestamp
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -136,4 +137,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/room_initial_sync.yaml

@@ -15,7 +15,8 @@ paths:
         [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: roomInitialSync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -175,4 +176,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/room_send.yaml

@@ -30,7 +30,8 @@ paths:
         [Room Events](/client-server-api/#room-events) for the m. event specification.
       operationId: sendMessage
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -110,4 +111,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/room_state.yaml

@@ -39,7 +39,8 @@ paths:
         being removed or are already present in the state event.
       operationId: setRoomStateWithKey
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -142,4 +143,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/room_upgrades.yaml

@@ -22,7 +22,8 @@ paths:
       description: Upgrades the given room to a particular room version.
       operationId: upgradeRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -106,4 +107,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/rooms.yaml

@@ -24,7 +24,8 @@ paths:
         retrieve this event e.g. by being a member in the room for this event.
       operationId: getOneRoomEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -78,7 +79,8 @@ paths:
         taken from the state of the room when they left.
       operationId: getRoomStateWithKey
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -128,7 +130,8 @@ paths:
       description: Get the state events for the current state of a room.
       operationId: getRoomState
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -234,7 +237,8 @@ paths:
               - leave
               - ban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: |-
@@ -284,7 +288,8 @@ paths:
           schema:
             type: string
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: A map of MXID to room member objects.
@@ -337,4 +342,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/search.yaml

@@ -22,7 +22,8 @@ paths:
       description: Performs a full text search across different categories.
       operationId: search
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: next_batch
@@ -374,4 +375,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/space_hierarchy.yaml

@@ -30,7 +30,8 @@ paths:
         rooms and parent events are not covered by this endpoint.
       operationId: getSpaceHierarchy
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -216,4 +217,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/sync.yaml

@@ -43,7 +43,8 @@ paths:
         events, alongside other state, when lazy-loading is not enabled.
       operationId: sync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: filter
@@ -544,4 +545,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/tags.yaml

@@ -23,7 +23,8 @@ paths:
       description: List the tags set by a user on a room.
       operationId: getRoomTags
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -83,7 +84,8 @@ paths:
       description: Add a tag to the room.
       operationId: setRoomTag
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -143,7 +145,8 @@ paths:
       description: Remove a tag from the room.
       operationId: deleteRoomTag
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -194,4 +197,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/third_party_lookup.yaml

@@ -25,7 +25,8 @@ paths:
         required for queries against each protocol.
       operationId: getProtocols
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The protocols supported by the homeserver.
@@ -42,7 +43,8 @@ paths:
         third-party protocol.
       operationId: getProtocolMetadata
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -85,7 +87,8 @@ paths:
         as reasonably possible given the network type.
       operationId: queryLocationByProtocol
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -129,7 +132,8 @@ paths:
         a set of user parameters.
       operationId: queryUserByProtocol
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -174,7 +178,8 @@ paths:
         alias.
       operationId: queryLocationByAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: alias
@@ -209,7 +214,8 @@ paths:
       description: Retrieve an array of third-party users from a Matrix User ID.
       operationId: queryUserByID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: userid
@@ -252,4 +258,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/third_party_membership.yaml

@@ -62,7 +62,8 @@ paths:
         append a `m.room.third_party_invite` event to the room.
       operationId: inviteBy3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -157,4 +158,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/threads_list.yaml

@@ -27,7 +27,8 @@ paths:
         user has participated in the thread.
       operationId: getThreadRoots
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -160,4 +161,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/to_device.yaml

@@ -24,7 +24,8 @@ paths:
         client devices.
       operationId: sendToDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: eventType
@@ -95,4 +96,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/typing.yaml

@@ -26,7 +26,8 @@ paths:
         user has stopped typing.
       operationId: setTyping
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -96,4 +97,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/users.yaml

@@ -32,7 +32,8 @@ paths:
         `Accept-Language` header provided in the request, if present.
       operationId: searchUserDirectory
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -122,4 +123,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/versions.yaml

@@ -45,7 +45,8 @@ paths:
       operationId: getVersions
       security:
         - {}
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       x-changedInMatrixVersion:
         "1.10": |
           This endpoint can behave differently when authentication is provided.
@@ -101,4 +102,7 @@ servers:
         default: /_matrix/client
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/voip.yaml

@@ -24,7 +24,8 @@ paths:
         calls.
       operationId: getTurnServer
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The TURN server credentials.
@@ -86,4 +87,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/whoami.yaml

@@ -30,7 +30,8 @@ paths:
         body.
       operationId: getTokenOwner
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token belongs to a known user.
@@ -112,4 +113,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/definitions/security.yaml

@@ -11,8 +11,17 @@
 # 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.
-accessToken:
+accessTokenQuery:
   type: apiKey
-  description: The access_token returned by a call to `/register`.
+  description: |-
+    The `access_token` returned by a call to `/register`, as a query parameter.
   name: access_token
   in: query
+accessTokenBearer:
+  type: http
+  description: |-
+    The `access_token` returned by a call to `/register`, using the
+    `Authorization: Bearer` header.
+    
+    This is the preferred method.
+  scheme: bearer

data/api/identity/v2_associations.yaml

@@ -23,7 +23,8 @@ paths:
       description: Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pidV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -128,7 +129,8 @@ paths:
         deprecated.
       operationId: bindV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -279,7 +281,8 @@ paths:
         homeserver is acting on behalf of a client.
       operationId: unbindV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -383,4 +386,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_auth.yaml

@@ -58,7 +58,8 @@ paths:
         request.
       operationId: getAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token holder's information.
@@ -99,7 +100,8 @@ paths:
         future requests to the server.
       operationId: logout
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token was successfully logged out.
@@ -150,4 +152,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_email_associations.yaml

@@ -40,7 +40,8 @@ paths:
         deprecated.
       operationId: emailRequestTokenV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -107,7 +108,8 @@ paths:
         deprecated.
       operationId: emailSubmitTokenPostV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -180,7 +182,8 @@ paths:
         used by end-users, and so the response should be human-readable.
       operationId: emailSubmitTokenGetV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -242,4 +245,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_invitation_signing.yaml

@@ -27,7 +27,8 @@ paths:
         to `store-invite`, and fetch the sender of the invite.
       operationId: blindlySignStuffV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -132,4 +133,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_lookup.yaml

@@ -28,7 +28,8 @@ paths:
         any of the algorithms defined in this specification.
       operationId: getHashDetails
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The hash function information.
@@ -70,7 +71,8 @@ paths:
         later in this specification.
       operationId: lookupUsersV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -162,4 +164,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_phone_associations.yaml

@@ -40,7 +40,8 @@ paths:
         deprecated.
       operationId: msisdnRequestTokenV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -109,7 +110,8 @@ paths:
         deprecated.
       operationId: msisdnSubmitTokenPostV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -182,7 +184,8 @@ paths:
         used by end-users, and so the response should be human-readable.
       operationId: msisdnSubmitTokenGetV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -243,4 +246,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_store_invite.yaml

@@ -51,7 +51,8 @@ paths:
         the `address` of the pending invite for display purposes.
       operationId: storeInviteV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -224,4 +225,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/identity/v2_terms.yaml

@@ -119,7 +119,8 @@ paths:
         may not be accepting all terms at once.
       operationId: agreeToTerms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -159,4 +160,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/server-server/backfill.yaml

@@ -162,4 +162,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/definitions/security.yaml

@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 signedRequest:
-  type: apiKey
+  type: http
   description: |-
-    The `Authorization` header defined in the [Authentication](/server-server-api/#authentication) section.
+    The `Authorization: X-Matrix` header defined in the [Authentication](/server-server-api/#authentication) 
-  name: Authorization
+    section.
-  in: header
+  scheme: X-Matrix

data/api/server-server/event_auth.yaml

@@ -75,4 +75,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/events.yaml

@@ -285,4 +285,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/invites-v1.yaml

@@ -194,4 +194,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/invites-v2.yaml

@@ -216,4 +216,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/joins-v1.yaml

@@ -407,4 +407,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/joins-v2.yaml

@@ -307,4 +307,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/knocks.yaml

@@ -355,4 +355,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/leaving-v1.yaml

@@ -263,4 +263,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/leaving-v2.yaml

@@ -148,4 +148,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/public_rooms.yaml

@@ -218,4 +218,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/query.yaml

@@ -196,4 +196,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/space_hierarchy.yaml

@@ -228,4 +228,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/third_party_invite.yaml

@@ -329,4 +329,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/transactions.yaml

@@ -111,4 +111,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/user_devices.yaml

@@ -120,4 +120,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

data/api/server-server/user_keys.yaml

@@ -252,4 +252,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest