---
title: "Claim one-time encryption keys."
method: POST
path: "/_matrix/client/v3/keys/claim"
tags: ["End-to-end encryption"]
---

# Claim one-time encryption keys.

`POST /_matrix/client/v3/keys/claim`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/keys/claim`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/keys/claim/post.ts> (a function with typed inputs; its response is checked against the schema)

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](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3keysupload). (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.

## Request body

- object
  - `one_time_keys` object, required: The keys to be claimed. A map from user ID, to a map from device ID to algorithm name.
  - `timeout` integer: The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default.

## Response `200`

The claimed keys.

- object
  - `failures` object: 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_keys` object, 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](https://spec.matrix.org/v1.19/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.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)