Authorisation

OAuth 2.0

Our API requests require specific permissions. For these permissions to be granted, you must be authenticated and authorised to perform the operation.

We, like many other public APIs (such as Google, Facebook, Twitter, Github), use the OAuth 2.0 protocol.

App Credentials

To perform any authorised tasks on our APIs, you must have a valid app identifier and secret. These will be provided manually by our technical team upon request. Please provide your required scope and callback URL with description of your app.

Your {APP_IDENTIFIER} will be a short, random string, that can be used in client side grants and should never change.

Your {APP_SECRET} will be a random string that you should not expose to clients. If someone was to get hold of your app secret, you can request that we reset it to another random string and we will resend you your credentials. Doing this will stop your existing credentials from working immediately.

Scopes

Your app will only be allowed to request access tokens with certain scopes. These will also be manually set to your needs when we set up your credentials.

measurement_analysis Allows you to read raw measurement data and health ranges. Designed for analysing and interpreting measurement data.
goal_analysis Allows you to read goals and latest measurements. Designed for analysing goals and producing exercise or diet plans.
front_end Allows you to read dashboard UI data and use the plain frame. Designed for displaying our graphical representations of the member's preferred data.
scan_performer Allows you to edit performers, edit readings and add measurements. Designed for adding measurements from an external peice of hardware.
scan_creator Allows you to create readings and get scan progress. Designed for starting and displaying progress of scans as they are performed.
scan_licenser Allows you to add new scan licenses. Designed for allowing scans after taking payment.
activity_offload Allows you to create new activity accumulations and add counts. Designed for adding activity from an external peice of hardware.
reporting Allows you to reading facility statistics and usage history. Designed for analysing facility performance.
user_management Allows you to read and write to your facility profile and create members. Designed for syncing membership data with member management systems.

Callback URL

Your callback URL is used as a security measure to restrict:

Authorisation Grants

We support a number of different authentication flows to obtain an access token, depending on the type of your application.

Authorisation Code

Our OAuth endpoints support the Authorisation Code grant for web servers written in server-side languages where the source code is not available to the public. This is the most common authentication flow.

Currently, we do not support a dialog for users to authorise the app if it is not already authorised. However, we grant access tokens for members of any facility that has given consent to your application. App consent is manually configured by our technical team upon request. To do this, you must direct the user to the following URL:

GET https://api.boditrax.com/oauth/auth?
    response_type=code&
    client_id={APP_IDENTIFIER}&
    redirect_uri={REDIRECT_URL}
                

If the user is not logged in, a login form will be displayed.

If the user is logged in as a member of a facility that has given consent to your application, this will redirect the user to the {REDIRECT_URL} with an authorisation code in the query string. Your web server can then exchange the authorisation code for an access token using the following URL:

POST https://api.boditrax.com/oauth/token
    grant_type=authorization_code&
    code={AUTHORISATION_CODE}&
    redirect_uri={REDIRECT_URL}&
    client_id={APP_IDENTIFIER}&
    client_secret={APP_SECRET}
                

If this is successful, the response will contain an access token in a response similar to the following:

{
    access_token: {ACCESS_TOKEN},
    token_type: "bearer",
    expires_in: 1800,
    refresh_token: {REFRESH_TOKEN}
}

Implicit Grant

Currently our API does not support the Implicit Grant for JavaScript, client-side applications where the source code is available to the user. However, this is planned for future releases.

Linked Account

For certain apps, our API supports the Resource Owner Password Credentials grant for previously linked accounts. This will not work with the user's boditrax login credentials.

The username field is used for the external username or userid stored in our linkedaccounts collection. The password field must be the external secret stored in the same collection and cannot be null.

GET https://api.boditrax.com/oauth/token?
    grant_type=password&
    client_id={APP_IDENTIFIER}&
    username={LINKED_ACCOUNT_USERNAME}&
    password={LINKED_ACCOUNT_SECRET}
                

App Credentials

Our OAuth endpoints support the Client Credentials grant for direct application access. This will give you limited access to certain features.

POST https://api.boditrax.com/oauth/token
    grant_type=client_credentials&
    client_id={APP_IDENTIFIER}&
    client_secret={APP_SECRET}
                

If this is successful, the response will contain an access token in a response similar to the following:

{
    access_token: {ACCESS_TOKEN},
    token_type: "bearer",
    expires_in: 1800,
    refresh_token: {REFRESH_TOKEN}
}

Using Access Tokens

To use the {ACCESS_TOKEN} in our API, all you have to do is include it in the HTTP Authorization header. Requests must be made of HTTPS.

Authorization: Bearer {ACCESS_TOKEN}

You may also include it as part of the querystring.

?access_token={ACCESS_TOKEN}

That's it! Now you're ready to start performing authorised requests to our API.

Access
Token

Refreshing Tokens

When your {ACCESS_TOKEN} expires, you can get a new one using the {REFRESH_TOKEN}. Please see Refreshing an Access Token in the OAuth spec.