Package io.github.ma1uta.matrix.identity.api

Interface SessionApi

  • @Path("/_matrix/identity/api/v1")
@Consumes("application/json")
@Produces("application/json")
public interface SessionApi
    The flow for creating an association is session-based.

    • Method Summary

      Modifier and Type Method Description
      void createEmailSession​(EmailRequestToken request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Create a session for validating an email address.
      void createPhoneSession​(PhoneRequestToken request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Create a session for validating a phone number.
      void getValidateEmail​(String sid, String clientSecret, String token, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Validate ownership of an email address.
      void getValidatePhone​(String sid, String clientSecret, String token, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Validate ownership of a phone number.
      void postValidateEmail​(SubmitToken request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Validate ownership of an email address.
      void postValidatePhone​(SubmitToken request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Validate ownership of a phone number.

    • Method Detail

      • createEmailSession

        @POST
@Path("/validate/email/requestToken")
void createEmailSession​(EmailRequestToken request,
                        @Context
                        javax.ws.rs.core.UriInfo uriInfo,
                        @Context
                        javax.ws.rs.core.HttpHeaders httpHeaders,
                        @Suspended
                        javax.ws.rs.container.AsyncResponse asyncResponse)
        Create a session for validating an email address.
        The identity server will send an email containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the email for that email address, and so we validate ownership of the email address.
        Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/email/requestToken is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server.
        Return: SessionResponse.

        Status code 200: Session created.

        Status code 400: An error ocurred. Some possible errors are:

        • M_INVALID_EMAIL: The email address provided was invalid.
        • M_EMAIL_SEND_ERROR: The validation email could not be sent.
        Parameters:
        request - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • postValidateEmail

        @POST
@Path("/validate/email/submitToken")
void postValidateEmail​(SubmitToken request,
                       @Context
                       javax.ws.rs.core.UriInfo uriInfo,
                       @Context
                       javax.ws.rs.core.HttpHeaders httpHeaders,
                       @Suspended
                       javax.ws.rs.container.AsyncResponse asyncResponse)
        Validate ownership of an email address.
        If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.
        The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.
        Return: ValidationResponse.

        Status code 200: The success of the validation.

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

      • getValidateEmail

        @GET
@Path("/validate/email/submitToken")
void getValidateEmail​(@QueryParam("sid")
                      String sid,
                      @QueryParam("client_secret")
                      String clientSecret,
                      @QueryParam("token")
                      String token,
                      @Context
                      javax.ws.rs.core.UriInfo uriInfo,
                      @Context
                      javax.ws.rs.core.HttpHeaders httpHeaders,
                      @Suspended
                      javax.ws.rs.container.AsyncResponse asyncResponse)
        Validate ownership of an email address.
        If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.
        Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.
        Return: EmptyResponse.

        Status code 200: Email address is validated.

        Status code 3xx: Email address is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

        Status code 4xx: Validation failed.

        Parameters:
        sid - Required. The session ID, generated by the requestToken call.
        clientSecret - Required. The client secret that was supplied to the requestToken call.
        token - Required. The token generated by the requestToken call and emailed to the user.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • createPhoneSession

        @POST
@Path("/validate/msisdn/requestToken")
void createPhoneSession​(PhoneRequestToken request,
                        @Context
                        javax.ws.rs.core.UriInfo uriInfo,
                        @Context
                        javax.ws.rs.core.HttpHeaders httpHeaders,
                        @Suspended
                        javax.ws.rs.container.AsyncResponse asyncResponse)
        Create a session for validating a phone number.
        The identity server will send an SMS message containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number.
        Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/msisdn/requestToken is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server.
        Return: SessionResponse.

        Status code 200: Session created.

        Status code 400: An error ocurred. Some possible errors are:

        • M_INVALID_ADDRESS: The phone number provided was invalid.
        • M_SEND_ERROR: The validation SMS could not be sent.
        • M_DESTINATION_REJECTED: The identity server cannot deliver an SMS to the provided country or region.
        Parameters:
        request - JSON body request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • postValidatePhone

        @POST
@Path("/validate/msisdn/submitToken")
void postValidatePhone​(SubmitToken request,
                       @Context
                       javax.ws.rs.core.UriInfo uriInfo,
                       @Context
                       javax.ws.rs.core.HttpHeaders httpHeaders,
                       @Suspended
                       javax.ws.rs.container.AsyncResponse asyncResponse)
        Validate ownership of a phone number.
        If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.
        The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.
        Return: ValidationResponse.

        Status code 200: The success of the validation.

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

      • getValidatePhone

        @GET
@Path("/validate/msisdn/submitToken")
void getValidatePhone​(@QueryParam("sid")
                      String sid,
                      @QueryParam("client_secret")
                      String clientSecret,
                      @QueryParam("token")
                      String token,
                      @Context
                      javax.ws.rs.core.UriInfo uriInfo,
                      @Context
                      javax.ws.rs.core.HttpHeaders httpHeaders,
                      @Suspended
                      javax.ws.rs.container.AsyncResponse asyncResponse)
        Validate ownership of a phone number.
        If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.
        Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.
        Return: EmptyResponse.

        Status code 200: Phone number is validated.

        Status code 3xx: Phone number is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

        Status code 4xx: Validation failed.

        Parameters:
        sid - Required. The session ID, generated by the requestToken call.
        clientSecret - Required. The client secret that was supplied to the requestToken call.
        token - Required. The token generated by the requestToken call and sent to the user.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.