Login Handlers

Introduction

You can implement your own HTTPS endpoints that allow your members to use boditrax using your own login credentials.

There are several actions the same handlers can be used for:

  • site - Directing users currently logged into your website to our online control panel, magically already logged in as their account.
  • kiosk - Logging into a boditrax kiosk seemlessly using your own credentials.
  • connect - Connecting existing boditrax accounts to your own linked accounts using your credentials.
  • mobile - Logging in from your own customised version of our mobile app.

Flow

With the exception of the site action, all flows follow a similar flow 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

The auth code endpoint gets a string that can be exchanged for the member details. It is used in all actions except for site.

Logging in

The users credentials will be sent directly to this endpoint with the {ACTION} in the querystring. The credentials will be in the x-www-form-urlencoded content body.

POST https://example.com/authcode?action={ACTION}
username={USERNAME}&password={PASSWORD}

The {ACTION} describes how the member info should be used and should be forwarded back to our API.

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

HTTP/1.1 302 Found
    Location: https://api.boditrax.com/handlers/{HANDLER_NAME}/{ACTION}?code={AUTH_CODE}

The {HANDLER_NAME} is the unique string to reference your member info endpoint URL stored in our database. This would usually be the name of your organisation.

The {ACTION} describes how the member info should be used. Some actions create new accounts if they don't already exist, some return JSON errors, some return 302 redirects.

The {AUTH_CODE} is a generated string and needs to be temporarily saved on your server as it will be exchanged for the member info 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 or mobile app.

{
        success: false,
        error: "invalid_credentials",
        message: "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},
        reference: {LICENSE_REFERENCE}
    }
}

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. If a {LICENSE_REFERENCE} is given and a scan license exists in our database with the same reference, that scan license will be updated instead.

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

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