---
title: "Upload cross-signing keys."
method: POST
path: "/_matrix/client/v3/keys/device_signing/upload"
tags: ["End-to-end encryption"]
---

# Upload cross-signing keys.

`POST /_matrix/client/v3/keys/device_signing/upload`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/keys/device_signing/upload`
- 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/device_signing/upload/post.ts> (a function with typed inputs; its response is checked against the schema)

Publishes cross-signing keys for the user.

This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api),
except when used by an application service.

User-Interactive Authentication MUST be performed for regular clients, except in these cases:
- there is no existing master signing key uploaded to the homeserver, OR
- there is an existing master signing key and it exactly matches the
  master signing key provided in the request body. If there are any additional
  keys provided in the request (self-signing key, user-signing key) they MUST also
  match the existing keys stored on the server. In other words, the request contains
  no new keys.

This allows clients to freely upload one set of keys, but not modify/overwrite keys if
they already exist. Allowing clients to upload the same set of keys more than once
makes this endpoint idempotent in the case where the response is lost over the network,
which would otherwise cause a UIA challenge upon retry.

**NOTE:** 
When this endpoint requires User-Interactive Authentication,
it uses the [`m.oauth`](https://spec.matrix.org/v1.19/client-server-api/#oauth-authentication)
authentication type if the access token was obtained
via the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).

## Request body

- object
  - `auth` object: Used by clients to submit authentication information to the interactive-authentication API
    - `session` string: The value of the session key given by the homeserver.
    - `type` string: The authentication type that the client is attempting to complete. May be omitted if `session` is given, and the client is reissuing a request which it believes has been completed out-of-band (for example, via the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).
  - `master_key` object: Key used for cross signing
    - `keys` object, required: The public key. The object must have exactly one property, whose name is in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value is the unpadded base64 public key.
    - `signatures` object: Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json). Optional for the master signing key. Other keys must be signed by the user\'s master signing key.
    - `usage` string[], required: What the key is used for.
    - `user_id` string, required: The ID of the user the key belongs to.
  - `self_signing_key` object: Key used for cross signing
    - `keys` object, required: The public key. The object must have exactly one property, whose name is in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value is the unpadded base64 public key.
    - `signatures` object: Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json). Optional for the master signing key. Other keys must be signed by the user\'s master signing key.
    - `usage` string[], required: What the key is used for.
    - `user_id` string, required: The ID of the user the key belongs to.
  - `user_signing_key` object: Key used for cross signing
    - `keys` object, required: The public key. The object must have exactly one property, whose name is in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value is the unpadded base64 public key.
    - `signatures` object: Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json). Optional for the master signing key. Other keys must be signed by the user\'s master signing key.
    - `usage` string[], required: What the key is used for.
    - `user_id` string, required: The ID of the user the key belongs to.

## Response `200`

The provided keys were successfully uploaded.

- object

## Other responses

- `400`: The input was invalid in some way. This can include one of the following error codes: * `M_INVALID_SIGNATURE`: For example, the self-signing or user-signing key had an incorrect signature. * `M_MISSING_PARAM`: No master signing key is available.
- `403`: The public key of one of the keys is the same as one of the user\'s device IDs, or the request is not authorised for any other reason.

---

[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)