---
title: "Link a Matrix account with a password login, the password is not stored"
method: POST
path: "/ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/account"
tags: ["matrix_account"]
---

# Link a Matrix account with a password login, the password is not stored

`POST /ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/account`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - HTTP basic

## Path parameters

- `apiVersion` 'v1', required

## Headers

- `OCS-APIRequest` boolean, required

## Request body

- object
  - `homeserverId` string, required: Id of the homeserver
  - `user` string, required: Matrix localpart or full user id
  - `password` string, required: Matrix password

## Response `201`

Account linked

- object
  - `ocs` object, required
    - `meta` OCSMeta, required
      - `status` string, required
      - `statuscode` integer, required
      - `message` string
      - `totalitems` string
      - `itemsperpage` string
    - `data` MatrixAccount, required
      - `id` string, required: SnowflakeID
      - `homeserverId` string, required: SnowflakeID of the homeserver
      - `mxid` string, required: Full Matrix user id, e.g. `@alice:example.org`
      - `deviceId` string, required: Matrix device id of Talk
      - `status` 0 | 1, required: 0 = active, 1 = the homeserver rejected the access token and the user has to log in again
      - `lastError` string, nullable, required: Error reported by the homeserver when it rejected the access token or the last sync failed
      - `lastSync` integer, required: Unix timestamp of the last sync, `0` if it never synced
      - `verified` boolean, nullable, required: Whether another device cross-signed the device of the server, null when encryption is not available on the server

## Other responses

- `400`: Invalid homeserver or user, account already linked or login rejected by the homeserver
- `401`: Wrong credentials
- `403`: User is not allowed to link an account
- `502`: Homeserver unreachable

## Changes

- **2026-10-12** `d31435356a15`: 1 info
  - added the required property `ocs/data/verified` to the response with the `201` status
- **2026-10-09** `d53448e507ad`: 1 info
  - added the required property `ocs/data/lastSync` to the response with the `201` status
- **2026-10-09** `4382ecd589de`: 2 info
  - added the required property `ocs/data/lastError` to the response with the `201` status
  - added the required property `ocs/data/status` to the response with the `201` status
- **2026-10-09** `3cff8058abe9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nextcloud/apis/spreed-full/changes/ocs/v2.php/apps/spreed/api/:apiVersion/matrix/account/post.md)

---

[API](https://skmtc.dev/nextcloud/apis/spreed-full.md) - [All operations](https://skmtc.dev/nextcloud/apis/spreed-full/llms.txt) - [OpenAPI document](https://skmtc.dev/nextcloud/apis/spreed-full/revisions/1d24d3b8fec0?raw)