Login Handlers

Introduction

You can implement your own HTTPS endpoints that allow your members to login to our kiosks using your own login credentials.

The flow is based on the OAuth 2.0 Authorization grant. You will need to implement two endpoints: your auth code endpoint and member info endpoint.

Auth Code Endpoint

Logging in

The users credentials will be sent directly from the kiosk to this endpoint. The credentials will be in the x-www-form-urlencoded content body of an AJAX request.

username={USERNAME}&password={PASSWORD}

Your server should then check the given credentials against your database and return a 302 redirect with your {APP_ID} and a generated {AUTH_CODE} in the query string.

HTTP/1.1 302 Found
    Location: https://api.boditrax.com/handlers/authcode?app={APP_ID}&code={AUTH_CODE}

The {APP_ID} is the unique app ID without the @apps.boditrax.com suffix.

The {AUTH_CODE} is a generated string and needs to be temporarily saved on your server as it will be exchanged for the member details later.

In the event of an error, the following JSON error response should be returned and the error text will be displayed on the kiosk.

{
        success: false,
        error: "Username and password combination is incorrect."
    }

Signing up

Registering new members is also available using the same endpoint. The request is very similar, except some extra arguments will be given in the request.

Your servers should then create the new member and return the exact same response with an {AUTH_CODE} for the new member. The rest of the flow will be exactly the same.

username={USERNAME}&password={PASSWORD}&firstname={FIRSTNAME}&lastname={LASTNAME}

Member Info Endpoint

Our servers will then exchange the {AUTH_CODE} for the member details. The {AUTH_CODE} will be in the x-www-form-urlencoded content body of the HTTPS request.

code={AUTH_CODE}

You should return the following JSON success response:

{
    success: true,
    linkedaccount: {
        type: {LINKED_ACCOUNT_TYPE},
        username: {LINKED_ACCOUNT_USERNAME},
        userid: {LINKED_ACCOUNT_USERID},
        secret: {LINKED_ACCOUNT_SECRET}
    },
    email: {EMAIL_ADDRESS},
    member: {
        firstname: "Connell",
        lastname: "Watkins",
        gender: "M",
        dateofbirth: "1982-05-05",
        height: 175
    },
    scanlicense: {
        scans: {SCANS_ALLOWED},
        expiry: {EXPIRY_DATE}
    }
}

The type and secret fields are mandatory. The username and userid fields are exclusive, i.e. you must include one but not both, depending how you set up the linkedaccounts collection. The email, member and scanlicense objects are all optional.

Our servers will first lookup the linked account based on the values in the linkedaccount object. If no member is found, we will attempt to find a member with the {EMAIL_ADDRESS} and will automatically link that account with the given details. If we still can't find the account, a new boditrax account will be created using the details in the member object and automatically linked.

If a scanlicense is given, we will automatically add the license to allow the member to perform a scan in the kiosk's facility.

In the event of an error, the standard error response should be returned. The error text will be forwarded to the kiosk.

{
    success: false,
    error: "Auth code is invalid."
}