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

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 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.