MAmatrix
Session management

Authenticates the user.

Authenticates the user, and issues an access token they can use to authorise themself in subsequent requests.

If the client does not supply a device_id, the server must auto-generate one.

The returned access token must be associated with the device_id supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See Relationship between access tokens and devices.

post/_matrix/client/v3/login

Request

Request body

addressstring

Third-party identifier for the user. Deprecated in favour of identifier.

device_idstring

ID of the client device. If this does not correspond to a known client device, a new device will be created. The given device ID must not be the same as a cross-signing key ID. The server will auto-generate a device_id if this is not specified.

initial_device_display_namestring

A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device.

mediumstring

When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of identifier.

passwordstring

Required when type is m.login.password. The user's password.

refresh_tokenboolean

If true, the client supports refresh tokens.

tokenstring

Required when type is m.login.token. Part of Token-based login.

typestring required

The login type being used.

This must be a type returned in one of the flows of the response of the GET /login endpoint, like m.login.password or m.login.token.

userstring

The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of identifier.

Example request

{
  "identifier": {
    "type": "m.id.user",
    "user": "cheeky_monkey"
  },
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "type": "m.login.password"
}

Response

The user has been authenticated.

access_tokenstring required

An access token for the account. This access token can then be used to authorise other requests.

device_idstring required

ID of the logged-in device. Will be the same as the corresponding parameter in the request, if one was specified.

expires_in_msinteger

The lifetime of the access token, in milliseconds. Once the access token has expired a new access token can be obtained by using the provided refresh token. If no refresh token is provided, the client will need to re-log in to obtain a new access token. If not given, the client can assume that the access token will not expire.

home_serverstring mx-server-name

The server_name of the homeserver on which the account has been registered.

Deprecated. Clients should extract the server_name from user_id (by splitting at the first colon) if they require it. Note also that homeserver is not spelt this way.

refresh_tokenstring

A refresh token for the account. This token can be used to obtain a new access token when it expires by calling the /refresh endpoint.

user_idstring mx-user-id required

The fully-qualified Matrix ID for the account.

Example response

{
  "well_known": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com"
    },
    "m.identity_server": {
      "base_url": "https://identity.example.com"
    },
    "org.example.custom.property": {
      "app_url": "https://custom.app.example.org"
    }
  }
}

Changes

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