1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/csapi/definitions/auth_data.h>
8
9#include <Quotient/jobs/basejob.h>
10
11namespace Quotient {
12
13/*! \brief Optional endpoint to generate a single-use, time-limited,
14 * `m.login.token` token.
15 *
16 * Optional endpoint - the server is not required to implement this endpoint if
17 * it does not intend to use or support this functionality.
18 *
19 * This API endpoint uses the [User-Interactive Authentication
20 * API](/client-server-api/#user-interactive-authentication-api).
21 *
22 * An already-authenticated client can call this endpoint to generate a
23 * single-use, time-limited, token for an unauthenticated client to log in with,
24 * becoming logged in as the same user which called this endpoint. The
25 * unauthenticated client uses the generated token in a `m.login.token` login
26 * flow with the homeserver.
27 *
28 * Clients, both authenticated and unauthenticated, might wish to hide user
29 * interface which exposes this feature if the server is not offering it.
30 * Authenticated clients can check for support on a per-user basis with the
31 * `m.get_login_token`
32 * [capability](/client-server-api/#capabilities-negotiation), while
33 * unauthenticated clients can detect server support by looking for an
34 * `m.login.token` login flow with `get_login_token: true` on [`GET
35 * /login`](/client-server-api/#post_matrixclientv3login).
36 *
37 * In v1.7 of the specification, transmission of the generated token to an
38 * unauthenticated client is left as an implementation detail. Future MSCs such
39 * as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)
40 * might standarise a way to transmit the token between clients.
41 *
42 * The generated token MUST only be valid for a single login, enforced by the
43 * server. Clients which intend to log in multiple devices must generate a token
44 * for each.
45 *
46 * With other User-Interactive Authentication (UIA)-supporting endpoints,
47 * servers sometimes do not re-prompt for verification if the session recently
48 * passed UIA. For this endpoint, servers should always re-prompt the user for
49 * verification to ensure explicit consent is gained for each additional client.
50 *
51 * Servers are encouraged to apply stricter than normal rate limiting to this
52 * endpoint, such as maximum of 1 request per minute.
53 */
54class QUOTIENT_API GenerateLoginTokenJob : public BaseJob {
55public:
56 /*! \brief Optional endpoint to generate a single-use, time-limited,
57 * `m.login.token` token.
58 *
59 * \param auth
60 * Additional authentication information for the user-interactive
61 * authentication API.
62 */
63 explicit GenerateLoginTokenJob(
64 const Omittable<AuthenticationData>& auth = none);
65
66 // Result properties
67
68 /// The login token for the `m.login.token` login flow.
69 QString loginToken() const
70 {
71 return loadFromJson<QString>(keyName: "login_token"_ls);
72 }
73
74 /// The time remaining in milliseconds until the homeserver will no longer
75 /// accept the token. `120000` (2 minutes) is recommended as a default.
76 int expiresInMs() const { return loadFromJson<int>(keyName: "expires_in_ms"_ls); }
77};
78
79} // namespace Quotient
80