generateLoginToken method

Future<GenerateLoginTokenResponse> generateLoginToken({ AuthenticationData? auth, })

Optional endpoint - the server is not required to implement this endpoint if it does not intend to use or support this functionality.

This API endpoint uses the User-Interactive Authentication API.

An already-authenticated client can call this endpoint to generate a single-use, time-limited, token for an unauthenticated client to log in with, becoming logged in as the same user which called this endpoint. The unauthenticated client uses the generated token in a m.login.token login flow with the homeserver.

Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes this feature if the server is not offering it. Authenticated clients can check for support on a per-user basis with the m.get_login_token capability, while unauthenticated clients can detect server support by looking for an m.login.token login flow with get_login_token: true on GET /login.

In v1.7 of the specification, transmission of the generated token to an unauthenticated client is left as an implementation detail. Future MSCs such as MSC3906 might standardise a way to transmit the token between clients.

The generated token MUST only be valid for a single login, enforced by the server. Clients which intend to log in multiple devices must generate a token for each.

With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt for verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt the user for verification to ensure explicit consent is gained for each additional client.

Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum of 1 request per minute.

auth Additional authentication information for the user-interactive authentication API.

Implementation

Future<GenerateLoginTokenResponse> generateLoginToken({
  AuthenticationData? auth,
}) async {
  final requestUri = Uri(path: '_matrix/client/v1/login/get_token');
  final request = Request('POST', baseUri!.resolveUri(requestUri));
  request.headers['authorization'] = 'Bearer ${bearerToken!}';
  request.headers['content-type'] = 'application/json';
  request.bodyBytes = utf8.encode(
    jsonEncode({
      if (auth != null) 'auth': auth.toJson(),
    }),
  );
  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 GenerateLoginTokenResponse.fromJson(json as Map<String, Object?>);
}