ruma_client_api/account/
register.rs

1//! `POST /_matrix/client/*/register`
2//!
3//! Register an account on this homeserver.
4
5use serde::{Deserialize, Serialize};
6
7pub mod v3 {
8    //! `/v3/` ([spec])
9    //!
10    //! [spec]: https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3register
11
12    use std::time::Duration;
13
14    use ruma_common::{
15        api::{request, response, Metadata},
16        metadata, OwnedDeviceId, OwnedUserId,
17    };
18
19    use super::{LoginType, RegistrationKind};
20    use crate::uiaa::{AuthData, UiaaResponse};
21
22    const METADATA: Metadata = metadata! {
23        method: POST,
24        rate_limited: true,
25        authentication: AppserviceTokenOptional,
26        history: {
27            1.0 => "/_matrix/client/r0/register",
28            1.1 => "/_matrix/client/v3/register",
29        }
30    };
31
32    /// Request type for the `register` endpoint.
33    #[request(error = UiaaResponse)]
34    #[derive(Default)]
35    pub struct Request {
36        /// The desired password for the account.
37        ///
38        /// May be empty for accounts that should not be able to log in again
39        /// with a password, e.g., for guest or application service accounts.
40        #[serde(skip_serializing_if = "Option::is_none")]
41        pub password: Option<String>,
42
43        /// Localpart of the desired Matrix ID.
44        ///
45        /// If omitted, the homeserver MUST generate a Matrix ID local part.
46        #[serde(skip_serializing_if = "Option::is_none")]
47        pub username: Option<String>,
48
49        /// ID of the client device.
50        ///
51        /// If this does not correspond to a known client device, a new device will be created.
52        /// The server will auto-generate a device_id if this is not specified.
53        #[serde(skip_serializing_if = "Option::is_none")]
54        pub device_id: Option<OwnedDeviceId>,
55
56        /// A display name to assign to the newly-created device.
57        ///
58        /// Ignored if `device_id` corresponds to a known device.
59        #[serde(skip_serializing_if = "Option::is_none")]
60        pub initial_device_display_name: Option<String>,
61
62        /// Additional authentication information for the user-interactive authentication API.
63        ///
64        /// Note that this information is not used to define how the registered user should be
65        /// authenticated, but is instead used to authenticate the register call itself.
66        /// It should be left empty, or omitted, unless an earlier call returned an response
67        /// with status code 401.
68        #[serde(skip_serializing_if = "Option::is_none")]
69        pub auth: Option<AuthData>,
70
71        /// Kind of account to register
72        ///
73        /// Defaults to `User` if omitted.
74        #[ruma_api(query)]
75        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
76        pub kind: RegistrationKind,
77
78        /// If `true`, an `access_token` and `device_id` should not be returned
79        /// from this call, therefore preventing an automatic login.
80        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
81        pub inhibit_login: bool,
82
83        /// Login `type` used by Appservices.
84        ///
85        /// Appservices can [bypass the registration flows][admin] entirely by providing their
86        /// token in the header and setting this login `type` to `m.login.application_service`.
87        ///
88        /// [admin]: https://spec.matrix.org/latest/application-service-api/#server-admin-style-permissions
89        #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
90        pub login_type: Option<LoginType>,
91
92        /// If set to `true`, the client supports [refresh tokens].
93        ///
94        /// [refresh tokens]: https://spec.matrix.org/latest/client-server-api/#refreshing-access-tokens
95        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
96        pub refresh_token: bool,
97    }
98
99    /// Response type for the `register` endpoint.
100    #[response(error = UiaaResponse)]
101    pub struct Response {
102        /// An access token for the account.
103        ///
104        /// This access token can then be used to authorize other requests.
105        ///
106        /// Required if the request's `inhibit_login` was set to `false`.
107        #[serde(skip_serializing_if = "Option::is_none")]
108        pub access_token: Option<String>,
109
110        /// The fully-qualified Matrix ID that has been registered.
111        pub user_id: OwnedUserId,
112
113        /// ID of the registered device.
114        ///
115        /// Will be the same as the corresponding parameter in the request, if one was specified.
116        ///
117        /// Required if the request's `inhibit_login` was set to `false`.
118        pub device_id: Option<OwnedDeviceId>,
119
120        /// A [refresh token] for the account.
121        ///
122        /// This token can be used to obtain a new access token when it expires by calling the
123        /// [`refresh_token`] endpoint.
124        ///
125        /// Omitted if the request's `inhibit_login` was set to `true`.
126        ///
127        /// [refresh token]: https://spec.matrix.org/latest/client-server-api/#refreshing-access-tokens
128        /// [`refresh_token`]: crate::session::refresh_token
129        #[serde(skip_serializing_if = "Option::is_none")]
130        pub refresh_token: Option<String>,
131
132        /// The lifetime of the access token, in milliseconds.
133        ///
134        /// Once the access token has expired, a new access token can be obtained by using the
135        /// provided refresh token. If no refresh token is provided, the client will need to
136        /// re-login to obtain a new access token.
137        ///
138        /// If this is `None`, the client can assume that the access token will not expire.
139        ///
140        /// Omitted if the request's `inhibit_login` was set to `true`.
141        #[serde(
142            with = "ruma_common::serde::duration::opt_ms",
143            default,
144            skip_serializing_if = "Option::is_none",
145            rename = "expires_in_ms"
146        )]
147        pub expires_in: Option<Duration>,
148    }
149
150    impl Request {
151        /// Creates a new `Request` with all parameters defaulted.
152        pub fn new() -> Self {
153            Default::default()
154        }
155    }
156
157    impl Response {
158        /// Creates a new `Response` with the given user ID.
159        pub fn new(user_id: OwnedUserId) -> Self {
160            Self {
161                access_token: None,
162                user_id,
163                device_id: None,
164                refresh_token: None,
165                expires_in: None,
166            }
167        }
168    }
169}
170
171/// The kind of account being registered.
172#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
173#[serde(rename_all = "snake_case")]
174#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
175pub enum RegistrationKind {
176    /// A guest account
177    ///
178    /// These accounts may have limited permissions and may not be supported by all servers.
179    Guest,
180
181    /// A regular user account
182    #[default]
183    User,
184}
185
186/// The login type.
187#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
188#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
189pub enum LoginType {
190    /// An appservice-specific login type
191    #[serde(rename = "m.login.application_service")]
192    ApplicationService,
193}
ruma_client_api/account/register.rs

ruma_client_api/account/
register.rs
