ruma_client_api/session/
refresh_token.rs

Help
1//! `POST /_matrix/client/*/refresh`
2//!
3//! Refresh an access token.
4//!
5//! Clients should use the returned access token when making subsequent API
6//! calls, and store the returned refresh token (if given) in order to refresh
7//! the new access token when necessary.
8//!
9//! After an access token has been refreshed, a server can choose to invalidate
10//! the old access token immediately, or can choose not to, for example if the
11//! access token would expire soon anyways. Clients should not make any
12//! assumptions about the old access token still being valid, and should use the
13//! newly provided access token instead.
14//!
15//! The old refresh token remains valid until the new access token or refresh
16//! token is used, at which point the old refresh token is revoked.
17//!
18//! Note that this endpoint does not require authentication via an access token.
19//! Authentication is provided via the refresh token.
20//!
21//! Application Service identity assertion is disabled for this endpoint.
22
23pub mod v3 {
24    //! `/v3/` ([spec])
25    //!
26    //! [spec]: https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3refresh
27
28    use std::time::Duration;
29
30    use ruma_common::{
31        api::{request, response, Metadata},
32        metadata,
33    };
34
35    const METADATA: Metadata = metadata! {
36        method: POST,
37        rate_limited: true,
38        authentication: None,
39        history: {
40            unstable => "/_matrix/client/unstable/org.matrix.msc2918/refresh",
41            1.3 => "/_matrix/client/v3/refresh",
42        }
43    };
44
45    /// Request type for the `refresh` endpoint.
46    #[request(error = crate::Error)]
47    pub struct Request {
48        /// The refresh token.
49        pub refresh_token: String,
50    }
51
52    /// Response type for the `refresh` endpoint.
53    #[response(error = crate::Error)]
54    pub struct Response {
55        /// The new access token to use.
56        pub access_token: String,
57
58        /// The new refresh token to use when the access token needs to be refreshed again.
59        ///
60        /// If this is `None`, the old refresh token can be re-used.
61        #[serde(skip_serializing_if = "Option::is_none")]
62        pub refresh_token: Option<String>,
63
64        /// The lifetime of the access token, in milliseconds.
65        ///
66        /// If this is `None`, the client can assume that the access token will not expire.
67        #[serde(
68            with = "ruma_common::serde::duration::opt_ms",
69            default,
70            skip_serializing_if = "Option::is_none"
71        )]
72        pub expires_in_ms: Option<Duration>,
73    }
74
75    impl Request {
76        /// Creates a new `Request` with the given refresh token.
77        pub fn new(refresh_token: String) -> Self {
78            Self { refresh_token }
79        }
80    }
81
82    impl Response {
83        /// Creates a new `Response` with the given access token.
84        pub fn new(access_token: String) -> Self {
85            Self { access_token, refresh_token: None, expires_in_ms: None }
86        }
87    }
88}
ruma_client_api/session/refresh_token.rs

ruma_client_api/session/
refresh_token.rs
