Skip to main content

Form Login

This page describes the user flow when a user tries to either login or sign up using form login.

Form login/ sign-up

SIGN-UP

To signup or register for the first time, the below API needs to be called:

  • api/auth/v1/signup . This is a POST request.

  • If an existing user tries to sign up/ register then the API returns a 409 with User Already exists as its response.

  • On successful signup, the response returns a 201 and a session cookie called qt-auth(in case of desktop) is set and a response header called x-qt-auth(in case of mobile) is created and set.

  • If any error occurs then the response returns Something went wrong. User could not be created.

    Usage

    Sample CURL

    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/signup' \
    --data-raw '{"email":"liluweb@goldeneggbrand.com",
    "username":"liluweb@goldeneggbrand.com",
    "metadata":{"phone-number":""},
    "password":"123456789",
    "name":"Alia",
    "dont-login":false}'

    Refer to Swagger API docs for more info on API usage.

    API Sequence Diagram

    signup

    Workflow 1 - Signup using OTP

  • After entering the user details for signup, an OTP will be sent to the user's email.

  • OTP can be configured to be sent through either email, phone number or both. (Client needs to contact support for the configuration).

  • Examples of email and sms providers include sendgrid mandrill and gupshup respectively.

  • /api/auth/v1/users/send-otp. This is a POST whose request body consits of the registered email id.

  • If the OTP is configured via email then the API returns 200 on successfully sending the OTP with a response message OTP can be configured and sent to either to the registered email id or phone number.

  • If OTP is not configured either via email or sms then API returns 500 with a response message Something went wrong. OTP was not sent through email or sms.

  • api/auth/v1/users/update-with-otp.This is a POST request whose payload consists of otp and user verification status.

  • This API will return 401 if the OTP is invalid or does not match.

    Usage

    Sample CURL

    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/send-otp' \
    --data-raw '{"email":"mauriziotrebini@neaeo.com"}'
    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/update-with-otp' \
    --data-raw '{"otp":"62537","user":{"verification-status":"email"}}'

    API Sequence Diagram

    otp
  • After entering the user details for signup, a verification link will be sent to the user's email.

  • api/auth/v1/users/send-verification-link. This is a POST request whose payload consists of email and redirect url.

  • The API returns 500 when there is something wrong with the verification link being sent with a response message as Something went wrong. verification link was not sent through email.

  • The API returns 200 on successfully sending the verification link with a response message as verification link was sent successfully, via email.

  • Clicking on the verify button from the verificationlink, it redirects the user back to the client domain.

  • api/auth/v1/users/verify. This is a GET request with token and redirect-url as its query string parameters.

  • When there is a redirect url present, the API returns a 302 with #email-verified attached to the redirect url in its location header.

  • When there is no redirect url present then the API returns a 200 with User has been verified. as its response.

    Usage

    Sample CURL

    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/send-verification-link' \
    --data-raw '{"email":"alia.test@gmail.com","redirect-url":"https://<publisher-website-url>/#email-verified"}'
    curl --location --request GET 'https://<publisher-website-url>/api/auth/v1/users/verify?token=cf7ecf7c-9309-4b01-ab09-5ce002752eac&redirect-url=<publisher-website-url>/' \

    API Sequence Diagram

    verification-link

LOGIN

To login with the user credentials, the below API needs to be called

  • api/auth/v1/login . This is a POST request whose payload will consist of username, email and password.

  • On successfully logging in the response returns 201 and a session cookie called qt-auth(in case of desktop) is set and a respomnse header called x-qt-auth(in case of mobile) is created and set.

  • When user is not active then the response returns User login failed.

  • When the user enters an invalid username or password then the response returns a 401 with Invalid username/password as its message.

    Usage

    Sample CURL

    curl --location --request POST '<publisher-website-url>/api/auth/v1/login' \
    --data-raw '{"username":"username.user@gmail.com",
    "email":"username.user@gmail.com",
    "password":"123*abc"}'

    API Sequence Diagram

    login