MAmatrix
End-to-end encryption

Claim one-time encryption keys.

Claims one-time keys for use in pre-key messages.

The request contains the user ID, device ID and algorithm name of the keys that are required. If a key matching these requirements can be found, the response contains it. The returned key is a one-time key if one is available, and otherwise a fallback key.

One-time keys are given out in the order that they were uploaded via /keys/upload. (All keys uploaded within a given call to /keys/upload are considered equivalent in this regard; no ordering is specified within them.)

Servers must ensure that each one-time key is returned at most once, so when a key has been returned, no other request will ever return the same key.

post/_matrix/client/v3/keys/claim

Request

Request body

one_time_keysobject required

The keys to be claimed. A map from user ID, to a map from device ID to algorithm name.

timeoutinteger

The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default.

Example request

{
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": "signed_curve25519"
    }
  },
  "timeout": 10000
}

Response

The claimed keys.

failuresobject

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.

one_time_keysobject required

One-time keys for the queried devices. A map from user ID, to a map from devices to a map from <algorithm>:<key_id> to the key object.

See the 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.

Example response

{
  "failures": {},
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "signed_curve25519:AAAAHg": {
          "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
          "signatures": {
            "@alice:example.com": {
              "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
            }
          }
        }
      }
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.