The POST /auth/token endpoint is used to create the authentication flow for a policyholder to login to a mobile or web application.

{
    "url": "https://api.bybits.co.uk/auth/token",
    "headers": {
        "client_secret": "11111-22222-33333-44444",
        "client_id": "11111-22222-33333-44444",
        "environment": "sandbox"
    },
    "method": "POST",
    "data": {}
}

First login

A policyholder can login for the first time using the username and password sent to their email at policy creation.

Stage 1 - USER_PASSWORD_AUTH

We use the temporary password that has been sent to the policyholder on policy creation to initiate the initial login.

// Request Payload
{
    "username": "policyholder_username",
    "password": "p0l1cy_5ecr3t!",
    "type": "USER_PASSWORD_AUTH"
}
// Response
{
    "username": "policyholder_username",
    "session": "yJraWQiOiJweUs2RHhFak05SXhnU3",
    "type": "NEW_PASSWORD_REQUIRED"
}

The response includes a session id that needs to be persistent in all future stages.

Stage 2 - NEW_PASSWORD_REQUIRED

We now need to set the user generated password. You will capture this password from the policyholder via your web or mobile application.

// Request Payload
{
    "username": "policyholder_username",
    "session": "yJraWQiOiJweUs2RHhFak05SXhnU3",
    "new_password": "new_p0l1cy_5ecr3t!",
    "type": "NEW_PASSWORD_REQUIRED"
}
// Response
{
    "type": "PASSWORD_RESET"
}

The password is now reset and the policyholder can login with the new details.

Stage 3 - Re-login with USER_PASSWORD_AUTH

// Request Payload
{
    "username": "policyholder_username",
    "password": "new_p0l1cy_5ecr3t!",
    "type": "USER_PASSWORD_AUTH"
}
// Response
{
    "username": "policyholder_username",
    "refresh_token": "ReYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0zX3JkdldSMGs",
    "access_token": "AcYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0zX3JkdldSMGs",
    "expiry": 1614864456,
    "type": "DONE"
}

The user will now be authenticated (type is DONE) and the access_token can be used to authenticate all subsequent request until it expires.

{
    "url": "https://api.bybits.co.uk/policys/details",
    "headers": {
        "authorization": "Bearer AcYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0zX3JkdldSMGs",
        "environment": "sandbox"
    },
    "method": "GET"
}

Subsequent logins

Only Stage 3 is needed in all subsequent login attempts.

Forgot password

There are two forgot password scenarios to be considered:

  1. The user has already logged in once and used the temporary password to create their own personal password
  2. The user still needs to use the temporary password to create their own personal password

If a policyholder needs to reset their password, then the POST /auth/token is used again, with type is FORGOT_PASSWORD.

// Request Payload
{
    "username": "policyholder_username",
    "type": "FORGOT_PASSWORD"
}
// Response
{
    "type": "FORGOT_PASSWORD_CODE"
}

The response above will be received for scenario 1 and the policyholder will be emailed a new reset password code. The email address will be the same that is associated with the policy.

// Request Payload
{
    "username": "policyholder_username",
    "new_password": "An0th3r_n3w_5ecr3t!",
    "code": "123456",
    "type": "FORGOT_PASSWORD_CODE"
}
// Response
{
    "type": "PASSWORD_RESET"
}

The policyholder will then be able to login with the new password.

For users in scenario 2, you will receive a response like:

//Response
{
    "type": "RESEND_PASSWORD"
}

This means that the temporary password has expired and will need to be reset. This can happen if the policyholder doesn't, on account creation, change their temporary password within 30 days.  When this happens, you need to create a new temporary password by sending the following payload:

//Request
{
    "username": "policyholder_username",
    "type": "RESEND_PASSWORD"
}

This will then move the policyholder back to Stage 2 - NEW_PASSWORD_REQUIRED as above.

We can check whether a user is in scenario 1 vs 2 by using the GET auth/users/:user_reference endpoint. This endpoint will provide the cognito_status of the user.

A user in scenario 1 will have a cognitio_status of CONFIRMED whereas a user in scenario 2 will have a cognito_status of FORCE_CHANGE_PASSWORD, for example:

//Response
{
    "f_names": "name",
    "l_names": "surname",
    "email": "email@email.com",
    "username": "some_username",
    "client_id": "some client id",
    "client_secret": "some client secret",
    "client_secret_sandbox": "some sandbox client secret",
    "role": "policyholder",
    "active": true,
    "created_at": "2021-10-07 11:05:11.124677",
    "updated_at": "2021-10-07 11:05:11.124677",
    "cognito_status": "FORCE_CHANGE_PASSWORD",
    "company_reference": "some company reference",
    "user_reference": "user reference",
    "policies": [
        "some policy reference"
    ]
}