#557: Integrate login to Swarmica via one-time password (OTP)

When integrating a technical support portal into a third-party application, the task arises of quickly and transparently authorizing the user in Swarmica.
Swarmica allows you to connect transparent application authorization through a cipher password obtained for a given user using a fixed OTP algorithm (one-time-password, one-time password).

Authorization algorithm

1. Upon successful registration/authorization in the integrated application, the application backend makes an API call to /api/auth/otp/code/request, passing the user data for which an authorization code needs to be created. The parameters of the call are similar to the API call Create user.
2. Swarmica finds an existing user with such data or creates a new account and returns the authorization code and user data in the response.
3. The frontend of the integrated application displays a link that should lead to the Swarmica portal:
   https://swarmica_address_tld/auth/otp/code/?data=...&errorUrl=...&redirectUrl=...
4. When following the link, Swarmica:
   1. In case of successful authorization, it either redirects the user to the specified redirectUrl, if this parameter is provided, or takes them to the basic page within Swarmica corresponding to the user's role.
   2. In case of an error, if the errorUrl parameter is specified, Swarmica redirects the user there, passing the errorMessage in the link parameters. If the parameter is not specified, the error is displayed on the Swarmica authorization page.

Link creation algorithm

The link on the frontend of the integrated application should consist of:

• The Swarmica portal address (https://swarmica__address__tld)
• The URI of the authorization page via OTP code. (/auth/otp/code)
• Parameters.:
  • data - is a mandatory parameter containing an authorization cipher in URLEncoded format
  • errorUrl - The URLEncoded address where the user will be redirected in case of authorization error, an optional parameter. The error message will be passed in the errorMessage parameter for this link.

    For example, when usingerrorUrl=https%3A%2F%2Fswarmica.ru, in case of an error Request failed with status code 404 the user will be forwarded tohttps://swarmica.ru?Request%20failed%20with%20status%20code%20404

  • redirectUrl - The URLEncoded address where the user will be redirected in case of successful authorization, an optional parameter.

Encryption algorithm

For correct user authorization, it is necessary to encrypt JSON data using a fixed encryption algorithm:

{
  "email": "someuser@email.tld",
  "code": "user_auth_code",
  "timestamp": 1742907325
}

For detailed instructions, contact Swarmica support.