Package io.github.ma1uta.matrix.client.api

Interface AccountApi

  • @Path("/_matrix/client/r0")
@Consumes("application/json")
@Produces("application/json")
public interface AccountApi
    Account registration and management.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  AccountApi.RegisterType
      The kind of account to register.

    • Method Summary

      Modifier and Type Method Description
      void available​(String username, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Checks to see if a username is available, and valid, for the server.
      void deactivate​(DeactivateRequest deactivateRequest, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Deactivate the user's account, removing all ability for the user to login again.
      void deleteThreePid​(Delete3PidRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Removes a third party identifier from the user's account.
      void emailRequestToken​(EmailRequestToken emailRequestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the identity server API validate/email/emailRequestToken, but first checks that the given email address is not already associated with an account on this Home Server.
      void getThreePid​(javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Gets a list of the third party identifiers that the homeserver has associated with the user's account.
      void msisdnRequestToken​(MsisdnRequestToken msisdnRequestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is not already associated with an account on this homeserver.
      void password​(PasswordRequest passwordRequest, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Changes the password for an account on this homeserver.
      void passwordEmailRequestToken​(EmailRequestToken requestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the identity server API validate/email/requestToken, but first checks that the given email address is associated with an account on this Home Server.
      void passwordMsisdnRequestToken​(MsisdnRequestToken requestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is associated with an account on this homeserver.
      void register​(String kind, RegisterRequest registerRequest, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Register for an account on this homeserver.
      void threePidEmailRequestToken​(EmailRequestToken requestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the identity server API validate/email/requestToken, but first checks that the given email address is not already associated with an account on this Home Server.
      void threePidMsisdnRequestToken​(MsisdnRequestToken requestToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is not already associated with an account on this homeserver.
      void updateThreePid​(ThreePidRequest threePidRequest, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Adds contact information to the user's account.
      void whoami​(javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)
      Gets information about the owner of a given access token.

    • Method Detail

      • register

        @POST
@Path("/register")
void register​(@QueryParam("kind")
              String kind,
              RegisterRequest registerRequest,
              @Context
              javax.ws.rs.core.UriInfo uriInfo,
              @Context
              javax.ws.rs.core.HttpHeaders httpHeaders,
              @Suspended
              javax.ws.rs.container.AsyncResponse asyncResponse)
        Register for an account on this homeserver.
        Return: LoginResponse.

        Status code 200: The account has been registered.

        Status code 400: Part of the request was invalid. This may include one of the following error codes:

        • M_USER_IN_USE : The desired user ID is already taken.
        • M_INVALID_USERNAME : The desired user ID is not a valid user name.
        • M_EXCLUSIVE : The desired user ID is in the exclusive namespace claimed by an application service.

        These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered whilst the client was performing authentication.

        Homeservers MUST perform the relevant checks and return these codes before performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication.

        Status code 401: The homeserver requires additional authentication information.

        Status code 429: This request was rate-limited.

        Parameters:
        kind - The kind of account to register. Defaults to user. One of: ["guest", "user"].
        registerRequest - JSON body parameters.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • emailRequestToken

        @POST
@Path("/register/email/requestToken")
void emailRequestToken​(EmailRequestToken emailRequestToken,
                       @Context
                       javax.ws.rs.core.UriInfo uriInfo,
                       @Context
                       javax.ws.rs.core.HttpHeaders httpHeaders,
                       @Suspended
                       javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the identity server API validate/email/emailRequestToken, but first checks that the given email address is not already associated with an account on this Home Server. Note that, for consistency, this API takes JSON objects, though the Identity Server API takes x-www-form-urlencoded parameters. See the Identity Server API for further information.
        Return: SessionResponse.

        Status code 200: An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error.

        Status code 400: Part of the request was invalid. This may include one of the following error codes:

        • M_THREEPID_IN_USE : The email address is already registered to an account on this server. However, if the home server has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the Home Server in question.
        • M_SERVER_NOT_TRUSTED : The id_server parameter refers to an ID server that is not trusted by this Home Server.

        Status code 403: The homeserver does not permit the address to be bound.

        Parameters:
        emailRequestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • msisdnRequestToken

        @POST
@Path("/register/msisdn/requestToken")
void msisdnRequestToken​(MsisdnRequestToken msisdnRequestToken,
                        @Context
                        javax.ws.rs.core.UriInfo uriInfo,
                        @Context
                        javax.ws.rs.core.HttpHeaders httpHeaders,
                        @Suspended
                        javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is not already associated with an account on this homeserver. See the Identity Service API for further information.
        Return: SessionResponse.

        Status code 200: An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error.

        Status code 400: Part of the request was invalid. This may include one of the following error codes:

        • M_THREEPID_IN_USE: The phone number is already registered to an account on this server. However, if the homeserver has the ability to send SMS message, it is recommended that the server instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number has an account on the homeserver in question.
        • M_SERVER_NOT_TRUSTED : The id_server parameter refers to an identity server that is not trusted by this homeserver.

        Status code 403: The homeserver does not permit the address to be bound.

        Parameters:
        msisdnRequestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • password

        @POST
@Path("/account/password")
void password​(PasswordRequest passwordRequest,
              @Context
              javax.ws.rs.core.UriInfo uriInfo,
              @Context
              javax.ws.rs.core.HttpHeaders httpHeaders,
              @Suspended
              javax.ws.rs.container.AsyncResponse asyncResponse,
              @Context
              javax.ws.rs.core.SecurityContext securityContext)
        Changes the password for an account on this homeserver.
        This API endpoint uses the User-Interactive Authentication API.
        An access token should be submitted to this endpoint if the client has an active session.
        The homeserver may change the flows available depending on whether a valid access token is provided.
        Rate-limited: Yes.
        Requires auth: Yes.
        Return: EmptyResponse.

        Status code 200: The password has been changed.

        Status code 401: The homeserver requires additional authentication information.

        Status code 429: This request was rate-limited.

        Parameters:
        passwordRequest - Password.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - Security context.

      • passwordEmailRequestToken

        @POST
@Path("/account/password/email/requestToken")
void passwordEmailRequestToken​(EmailRequestToken requestToken,
                               @Context
                               javax.ws.rs.core.UriInfo uriInfo,
                               @Context
                               javax.ws.rs.core.HttpHeaders httpHeaders,
                               @Suspended
                               javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the identity server API validate/email/requestToken, but first checks that the given email address is associated with an account on this Home Server. This API should be used to request validation tokens when authenticating for the account/password endpoint. This API's parameters and response are identical to that of the HS API /register/email/requestToken except that M_THREEPID_NOT_FOUND may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. M_THREEPID_IN_USE may not be returned.
        Return: SessionResponse.

        Status code 200: An email was sent to the given address.

        Status code 400: The referenced third party identifier is not recognised by the homeserver, or the request was invalid.

        Status code 403: The homeserver does not allow the third party identifier as a contact option.

        Parameters:
        requestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • passwordMsisdnRequestToken

        @POST
@Path("/account/password/msisdn/requestToken")
void passwordMsisdnRequestToken​(MsisdnRequestToken requestToken,
                                @Context
                                javax.ws.rs.core.UriInfo uriInfo,
                                @Context
                                javax.ws.rs.core.HttpHeaders httpHeaders,
                                @Suspended
                                javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the account/password endpoint. This API's parameters and response are identical to that of the HS API /register/msisdn/requestToken except that M_THREEPID_NOT_FOUND may be returned if no account matching the given phone number could be found. The server may instead send an SMS message to the given address prompting the user to create an account. M_THREEPID_IN_USE may not be returned.
        Return: SessionResponse.

        Status code 200: An SMS message was sent to the given phone number.

        Status code 400: The referenced third party identifier is not recognised by the homeserver, or the request was invalid.

        Status code 403: The homeserver does not allow the third party identifier as a contact option.

        Parameters:
        requestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • deactivate

        @POST
@Path("/account/deactivate")
void deactivate​(DeactivateRequest deactivateRequest,
                @Context
                javax.ws.rs.core.UriInfo uriInfo,
                @Context
                javax.ws.rs.core.HttpHeaders httpHeaders,
                @Suspended
                javax.ws.rs.container.AsyncResponse asyncResponse,
                @Context
                javax.ws.rs.core.SecurityContext securityContext)
        Deactivate the user's account, removing all ability for the user to login again.
        This API endpoint uses the User-Interactive Authentication API.
        An access token should be submitted to this endpoint if the client has an active session.
        The homeserver may change the flows available depending on whether a valid access token is provided.
        Rate-limited: Yes.
        Requires auth: Yes.
        Return: DeactivateResponse.

        Status code 200: The account has been deactivated.

        Status code 401: The homeserver requires additional authentication information.

        Status code 429: This request was rate-limited.

        Parameters:
        deactivateRequest - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - Security context.

      • available

        @GET
@Path("/register/available")
void available​(@QueryParam("username")
               String username,
               @Context
               javax.ws.rs.core.UriInfo uriInfo,
               @Context
               javax.ws.rs.core.HttpHeaders httpHeaders,
               @Suspended
               javax.ws.rs.container.AsyncResponse asyncResponse)
        Checks to see if a username is available, and valid, for the server.
        The server should check to ensure that, at the time of the request, the username requested is available for use. This includes verifying that an application service has not claimed the username and that the username fits the server's desired requirements (for example, a server could dictate that it does not permit usernames with underscores).
        Matrix clients may wish to use this API prior to attempting registration, however the clients must also be aware that using this API does not normally reserve the username. This can mean that the username becomes unavailable between checking its availability and attempting to register it.
        Rate-limited: Yes.
        Return: AvailableResponse.

        Status code 200: The username is available.

        Status code 400: Part of the request was invalid or the username is not available. This may include one of the following error codes:

        • M_USER_IN_USE : The desired username is already taken.
        • M_INVALID_USERNAME : The desired username is not a valid user name.
        • M_EXCLUSIVE : The desired username is in the exclusive namespace claimed by an application service.

        Status code 429: This request was rate-limited.

        Parameters:
        username - Required. The username to check the availability of.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • getThreePid

        @GET
@Path("/account/3pid")
void getThreePid​(@Context
                 javax.ws.rs.core.UriInfo uriInfo,
                 @Context
                 javax.ws.rs.core.HttpHeaders httpHeaders,
                 @Suspended
                 javax.ws.rs.container.AsyncResponse asyncResponse,
                 @Context
                 javax.ws.rs.core.SecurityContext securityContext)
        Gets a list of the third party identifiers that the homeserver has associated with the user's account.
        This is not the same as the list of third party identifiers bound to the user's Matrix ID in Identity Servers.
        Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password.
        Requires auth: Yes.
        Return: ThreePidResponse.

        Status code 200: The lookup was successful.

        Parameters:
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - security context.

      • updateThreePid

        @POST
@Path("/account/3pid")
void updateThreePid​(ThreePidRequest threePidRequest,
                    @Context
                    javax.ws.rs.core.UriInfo uriInfo,
                    @Context
                    javax.ws.rs.core.HttpHeaders httpHeaders,
                    @Suspended
                    javax.ws.rs.container.AsyncResponse asyncResponse,
                    @Context
                    javax.ws.rs.core.SecurityContext securityContext)
        Adds contact information to the user's account.
        Requires auth: Yes.
        Return: EmptyResponse.

        Status code 200: The addition was successful.

        Status code 403: The credentials could not be verified with the identity server.

        Parameters:
        threePidRequest - New contact information.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - Security context.

      • deleteThreePid

        @POST
@Path("/account/3pid/delete")
void deleteThreePid​(Delete3PidRequest request,
                    @Context
                    javax.ws.rs.core.UriInfo uriInfo,
                    @Context
                    javax.ws.rs.core.HttpHeaders httpHeaders,
                    @Suspended
                    javax.ws.rs.container.AsyncResponse asyncResponse,
                    @Context
                    javax.ws.rs.core.SecurityContext securityContext)
        Removes a third party identifier from the user's account. This might not cause an unbind of the identifier from the identity server.
        Requires auth: Yes.
        Return: DeactivateResponse.

        Status code 200: The homeserver has disassociated the third party identifier from the user.

        Parameters:
        request - JSON body request to delete 3pid.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - Security context.

      • threePidEmailRequestToken

        @POST
@Path("/account/3pid/email/requestToken")
void threePidEmailRequestToken​(EmailRequestToken requestToken,
                               @Context
                               javax.ws.rs.core.UriInfo uriInfo,
                               @Context
                               javax.ws.rs.core.HttpHeaders httpHeaders,
                               @Suspended
                               javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the identity server API validate/email/requestToken, but first checks that the given email address is not already associated with an account on this Home Server. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response is identical to that of the HS API /register/email/requestToken endpoint.
        Return: SessionResponse.

        Status code 200: An email was sent to the given address.

        Status code 400: The third party identifier is already in use on the homeserver, or the request was invalid.

        Status code 403: The homeserver does not allow the third party identifier as a contact option.

        Parameters:
        requestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • threePidMsisdnRequestToken

        @POST
@Path("/account/3pid/msisdn/requestToken")
void threePidMsisdnRequestToken​(MsisdnRequestToken requestToken,
                                @Context
                                javax.ws.rs.core.UriInfo uriInfo,
                                @Context
                                javax.ws.rs.core.HttpHeaders httpHeaders,
                                @Suspended
                                javax.ws.rs.container.AsyncResponse asyncResponse)
        Proxies the Identity Service API validate/msisdn/requestToken, but first checks that the given phone number is not already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the /register/msisdn/requestToken endpoint.
        Return: SessionResponse.

        Status code 200: An SMS message was sent to the given phone number.

        Status code 400: The third party identifier is already in use on the homeserver, or the request was invalid.

        Status code 403: The homeserver does not allow the third party identifier as a contact option.

        Parameters:
        requestToken - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • whoami

        @GET
@Path("/account/whoami")
void whoami​(@Context
            javax.ws.rs.core.UriInfo uriInfo,
            @Context
            javax.ws.rs.core.HttpHeaders httpHeaders,
            @Suspended
            javax.ws.rs.container.AsyncResponse asyncResponse,
            @Context
            javax.ws.rs.core.SecurityContext securityContext)
        Gets information about the owner of a given access token.
        Note that, as with the rest of the Client-Server API, Application Services may masquerade as users within their namespace by giving a user_id query parameter. In this situation, the server should verify that the given user_id is registered by the appservice, and return it in the response body.
        Rate-limited: Yes.
        Requires auth: Yes.
        Return: WhoamiResponse.

        Status code 200: The token belongs to a known user.

        Status code 401: The token is not recognised.

        Status code 403: The appservice cannot masquerade as the user or has not registered them.

        Status code 429: This request was rate-limited.

        Parameters:
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.
        securityContext - Security context.