BACtrack Service

BACtrack users have store hundreds of thousands of BAC readings to the cloud. BAC readings contain rich metadata like location, photos, and notes. Many users opt in to allow readings to be viewed anonymously. This unique dataset can be accessed by developers for use in statistcal analysis, data mashups, or use in your app. Here are some examples of our data in action: * BACtrack Consumption Report * BACtrack WorldView * In your own app, you can authenticate users to let them view their account data.

Authentication

The BACtrack data API uses OAuth 1.0a for authentication. OAuth is a protocol that allows the user grant your app access to our web service on his behalf without telling you his login credentials. OAuth defines a workflow that allows the user to log in to our site at your request to create an access token that will allow you to request data from the service on his behalf.

OAuth Signing

These docs don’t describe how to sign each request. The OAuth site has a description of the signing process. However, most developers do not implement OAuth signing themselves since there are several available libraries. In Python, for exmaple, a frequently used library would be oauthlib.

Steps to Obtain an Access Token

As you read the overview of the OAuth authentication protocol below, it might help to follow along on this diagram.

1. The Consumer (your app) requests a Request Token from the Provider (our service) at https://mobile.bactrack.com/oauth/request_token/. The Consumer’s request must be signed with a valid Consumer Secret (see above for a discussion of signing). The request does not need to include any oauth_token in the header. The response will consist of a Request Token and a Request Token Secret.
2. The Consumer requests (and shows to the user) the login (authorization) page at https://mobile.bactrack.com/oauth/authorize/. The request for this page should use the Request Token as its oauth_token and compute the oauth_signature using the Request Token Secret.
3. After the user has logged in and authorized the Consumer, the Consumer can now use the validated Request Token to request an Access Token at https://mobile.bactrack.com/oauth/access_token/. This request should be signed using the Request Token Secret. The response will consist of an Access Token and Access Token Secret.

For all of these steps and for general API usage, the oauth parameters should be passed via the HTTP-Authorization header. If the HTTP-Authorization header is not available, we also accept these parameters as url-encoded query string parameters.

Important: You must set the header Content-Type: application/json in every request. Alternatively, you can add ?format=json to all requests.

Note that in OAuth jargon, a key is like a username, and a secret is the corresponding password. The parameter names are as follows:

oauth_consumer_key

The public key for your app. This is different than your hardware API Key. Please contact [email protected] to get a Web API Key.

oauth_nonce

A one time random string that you generate per request. This protects against replay attacks. Nonce is short for for “number, used once.”

oauth_signature

Signature for the request. Signed with the appropriate secret key using the technique from https://oauth.net/core/1.0a/#signing_process. It is probably easiest to find a library to do this signing for you. For example, Python’s oauthlib.

oauth_signature_method

Must be HMAC-SHA1. We do not support plaintext signing.

oauth_timestamp

Must be a recent timestamp in seconds since the epoch.

oauth_token

The appropriate token, depending on which phase of the OAuth procedure you’re performing.

oauth_version

Must be 1.0