# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # Copyright 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 Client Config API version: 1.0.0 paths: /keys/upload: post: summary: Upload end-to-end encryption keys. description: Publishes end-to-end encryption keys for the device. operationId: uploadKeys security: - accessToken: [] requestBody: content: application/json: schema: type: object properties: device_keys: description: |- Identity keys for the device. May be absent if no new identity keys are required. allOf: - $ref: definitions/device_keys.yaml one_time_keys: # $ref: "definitions/one_time_keys.yaml" # XXX: We can't define an actual object here, so we have to hope # that people will look at the swagger source or can figure it out # from the other endpoints/example. type: object title: OneTimeKeys description: |- One-time public keys for "pre-key" messages. The names of the properties should be in the format `:`. The format of the key is determined by the [key algorithm](/client-server-api/#key-algorithms). May be absent if no new one-time keys are required. example: curve25519:AAAAAQ: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8 signed_curve25519:AAAAHg: key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs signatures: "@alice:example.com": ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw signed_curve25519:AAAAHQ: key: j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw signatures: "@alice:example.com": ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA fallback_keys: x-addedInMatrixVersion: "1.2" # $ref: "definitions/one_time_keys.yaml" # XXX: We can't define an actual object here - see above. type: object title: OneTimeKeys description: |- The public key which should be used if the device's one-time keys are exhausted. The fallback key is not deleted once used, but should be replaced when additional one-time keys are being uploaded. The server will notify the client of the fallback key being used through `/sync`. There can only be at most one key per algorithm uploaded, and the server will only persist one key per algorithm. When uploading a signed key, an additional `fallback: true` key should be included to denote that the key is a fallback key. May be absent if a new fallback key is not required. example: curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8 signed_curve25519:AAAAGj: key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs fallback: true signatures: "@alice:example.com": ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw description: The keys to be published required: true responses: "200": description: The provided keys were successfully uploaded. content: application/json: schema: type: object properties: one_time_key_counts: type: object additionalProperties: type: integer description: |- For each key algorithm, the number of unclaimed one-time keys of that type currently held on the server for this device. If an algorithm is not listed, the count for that algorithm is to be assumed zero. example: curve25519: 10 signed_curve25519: 20 required: - one_time_key_counts tags: - End-to-end encryption /keys/query: post: summary: Download device identity keys. description: Returns the current devices and identity keys for the given users. operationId: queryKeys security: - accessToken: [] requestBody: content: application/json: schema: type: object properties: timeout: type: integer description: |- The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default. example: 10000 device_keys: type: object description: |- The keys to be downloaded. A map from user ID, to a list of device IDs, or to an empty list to indicate all devices for the corresponding user. additionalProperties: type: array items: type: string description: device ID example: "@alice:example.com": [] required: - device_keys description: Query defining the keys to be downloaded required: true responses: "200": description: The device information content: application/json: schema: type: object properties: failures: type: object description: |- If any remote homeservers could not be reached, they are recorded here. The names of the properties are the names of the unreachable servers. If the homeserver could be reached, but the user or device was unknown, no failure is recorded. Instead, the corresponding user or device is missing from the `device_keys` result. additionalProperties: type: object example: {} device_keys: type: object description: |- Information on the queried devices. A map from user ID, to a map from device ID to device information. For each device, the information returned will be the same as uploaded via `/keys/upload`, with the addition of an `unsigned` property. additionalProperties: type: object additionalProperties: title: DeviceInformation allOf: - $ref: definitions/device_keys.yaml properties: unsigned: title: UnsignedDeviceInfo type: object description: |- Additional data added to the device key information by intermediate servers, and not covered by the signatures. properties: device_display_name: type: string description: The display name which the user set on the device. example: "@alice:example.com": JLAFKJWSCS: user_id: "@alice:example.com" device_id: JLAFKJWSCS algorithms: - m.olm.v1.curve25519-aes-sha2 - m.megolm.v1.aes-sha2 keys: curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI signatures: "@alice:example.com": ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA unsigned: device_display_name: Alice's mobile phone master_keys: x-addedInMatrixVersion: "1.1" type: object description: |- Information on the master cross-signing keys of the queried users. A map from user ID, to master key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`, along with the signatures uploaded via `/keys/signatures/upload` that the requesting user is allowed to see. additionalProperties: allOf: - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" usage: - master keys: ed25519:base64+master+public+key: base64+master+public+key self_signing_keys: x-addedInMatrixVersion: "1.1" type: object description: |- Information on the self-signing keys of the queried users. A map from user ID, to self-signing key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`. additionalProperties: allOf: - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" usage: - self_signing keys: ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key signatures: "@alice:example.com": ed25519:base64+master+public+key: signature+of+self+signing+key user_signing_keys: type: object description: |- Information on the user-signing key of the user making the request, if they queried their own device information. A map from user ID, to user-signing key information. The information returned will be the same as uploaded via `/keys/device_signing/upload`. additionalProperties: allOf: - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" usage: - user_signing keys: ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key signatures: "@alice:example.com": ed25519:base64+master+public+key: signature+of+user+signing+key tags: - End-to-end encryption /keys/claim: post: summary: Claim one-time encryption keys. description: Claims one-time keys for use in pre-key messages. operationId: claimKeys security: - accessToken: [] requestBody: content: application/json: schema: type: object properties: timeout: type: integer description: |- The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default. example: 10000 one_time_keys: type: object description: |- The keys to be claimed. A map from user ID, to a map from device ID to algorithm name. additionalProperties: type: object additionalProperties: type: string description: algorithm example: signed_curve25519 example: "@alice:example.com": JLAFKJWSCS: signed_curve25519 required: - one_time_keys description: Query defining the keys to be claimed required: true responses: "200": description: The claimed keys. content: application/json: schema: type: object properties: failures: type: object description: |- If any remote homeservers could not be reached, they are recorded here. The names of the properties are the names of the unreachable servers. If the homeserver could be reached, but the user or device was unknown, no failure is recorded. Instead, the corresponding user or device is missing from the `one_time_keys` result. additionalProperties: type: object example: {} one_time_keys: type: object description: |- One-time keys for the queried devices. A map from user ID, to a map from devices to a map from `:` to the key object. See the [key algorithms](/client-server-api/#key-algorithms) section for information on the Key Object format. If necessary, the claimed key might be a fallback key. Fallback keys are re-used by the server until replaced by the device. additionalProperties: type: object additionalProperties: # $ref: "definitions/one_time_keys.yaml" # XXX: We can't define an actual object here, so we have to hope # that people will read the link provided in the description # and figure it out from the other endpoints/example. # See also one_time_key parameter for /keys/upload above. type: object title: OneTimeKeys example: "@alice:example.com": JLAFKJWSCS: signed_curve25519:AAAAHg: key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs signatures: "@alice:example.com": ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw required: - one_time_keys tags: - End-to-end encryption /keys/changes: get: summary: Query users with recent device key updates. description: |- Gets a list of users who have updated their device identity keys since a previous sync token. The server should include in the results any users who: * currently share a room with the calling user (ie, both users have membership state `join`); *and* * added new device identity keys or removed an existing device with identity keys, between `from` and `to`. operationId: getKeysChanges security: - accessToken: [] parameters: - in: query name: from description: |- The desired start point of the list. Should be the `next_batch` field from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not uploaded new device identity keys since this point, nor deleted existing devices with identity keys since then, will be excluded from the results. required: true example: s72594_4483_1934 schema: type: string - in: query name: to description: |- The desired end point of the list. Should be the `next_batch` field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent such call. This may be used by the server as a hint to check its caches are up to date. required: true example: s75689_5632_2435 schema: type: string responses: "200": description: The list of users who updated their devices. content: application/json: schema: type: object properties: changed: type: array items: type: string description: |- The Matrix User IDs of all users who updated their device identity keys. example: - "@alice:example.com" - "@bob:example.org" left: type: array items: type: string description: |- The Matrix User IDs of all users who may have left all the end-to-end encrypted rooms they previously shared with the user. example: - "@clara:example.com" - "@doug:example.org" 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: $ref: definitions/security.yaml