login method

Future<LoginResponse> login(String type, { String? address, String? deviceId, AuthenticationIdentifier? identifier, String? initialDeviceDisplayName, String? medium, String? password, bool? refreshToken, String? token, String? user, })

Authenticates the user, and issues an access token they can use to authorize 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.

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

deviceId 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.

identifier Identification information for a user

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

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

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

refreshToken If true, the client supports refresh tokens.

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

type 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.

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

Implementation

Future<LoginResponse> login(
  String type, {
  String? address,
  String? deviceId,
  AuthenticationIdentifier? identifier,
  String? initialDeviceDisplayName,
  String? medium,
  String? password,
  bool? refreshToken,
  String? token,
  String? user,
}) async {
  final requestUri = Uri(path: '_matrix/client/v3/login');
  final request = Request('POST', baseUri!.resolveUri(requestUri));
  request.headers['content-type'] = 'application/json';
  request.bodyBytes = utf8.encode(
    jsonEncode({
      if (address != null) 'address': address,
      if (deviceId != null) 'device_id': deviceId,
      if (identifier != null) 'identifier': identifier.toJson(),
      if (initialDeviceDisplayName != null)
        'initial_device_display_name': initialDeviceDisplayName,
      if (medium != null) 'medium': medium,
      if (password != null) 'password': password,
      if (refreshToken != null) 'refresh_token': refreshToken,
      if (token != null) 'token': token,
      'type': type,
      if (user != null) 'user': user,
    }),
  );
  final response = await httpClient.send(request);
  final responseBody = await response.stream.toBytes();
  if (response.statusCode != 200) unexpectedResponse(response, responseBody);
  final responseString = utf8.decode(responseBody);
  final json = jsonDecode(responseString);
  return LoginResponse.fromJson(json as Map<String, Object?>);
}