Make your product
work with UP.

Authentication

UP API uses OAuth 2.0 protocol to authenticate incoming requests. A client_id and client_secret is assigned to each application created by a Developer. The Developer can then request authorization from the user to access user’s data and obtain an Access Token, which will be used for further requests. This token will have an extended expiration time and the Developer can store the token and use it for multiple calls.

IMPORTANT: All communication should be done over a secure channel (SSL). HTTPS redirect uri is a requirement for authentication when an app is published.

Calls on behalf of the user

To make calls on behalf of the user, the Developer needs to get explicit permission from the user via a 3-legged authentication mechanism.

The flow is as follows:

  1. User is redirected to the UP authentication page (https://jawbone.com/auth/oauth2/auth) passing:
    1. response_type=code: must have the value "code" to obtain the authorization code.
    2. client_id: unique identifier obtained from the dev portal.
    3. scope: space-delimited list of permissions you will be asking the user (see below for a detailed description of each scope).
    4. redirect_uri: URI where to redirect the user after he/she grants permissions. This URI must match one of the URI prefixes defined when setting up API access.
  2. If the user is not logged in, then he’ll be asked to enter their user and password. After the user logs in, he’ll see the list of permissions being asked, and needs to accept the request.
  3. If the user accepts, then he’s redirected back to the Developer’s site, using the redirect_uri, and passing the authorization code in the query parameter. For example: http://developer_example.com/access?code=ABC123. This authorization code has an expiration of 10 minutes.
  4. Last step, is for the Developer to exchange the authorization code with an access token. For this, the Developer must make an HTTPS call (server to server) to obtain the access token (https://jawbone.com/auth/oauth2/token) passing:
    1. client_id: unique identifier obtained from the dev portal.
    2. client_secret: secret key obtained from the dev portal.
    3. grant_type=authorization_code: must have the value “authorization_code” to exchange the token.
    4. code: the authorization code sent by UP on the previous step.
  5. The server will return a JSON object with the access token. This token will have an expiration of 1 year. It will also return a refresh token used to request a new access token for the user when the current access token issued expires.
  6. With the access token, the Developer can make API calls on behalf of the user, by passing the code in the Authorization: Bearer header.
    GET /nudge/api/users/@me HTTP/1.1
    Host: api.example.com
    Authorization: Bearer DCEOB729f3i5CuLCyZCkX_5slG_fpc1IhNqf0FnfK_YDmmc7bZ
    	

To refresh an access token

The refresh token received along with the access token via OAuth can be used to request a new access token. Typically access tokens are refreshed when the current access token has expired or has been compromised. If you did not store the refresh token when it was issued with the original access token you can retrieve it via the refresh token endpoint here.

In order to refresh an access token make an HTTP POST call to (https://jawbone.com/auth/oauth2/token) passing:

  1. client_id: unique identifier obtained from the dev portal.
  2. client_secret: secret key obtained from the dev portal.
  3. grant_type=refresh_token: must have the value “refresh_token” to exchange the access token.
  4. refresh_token: the refresh token received via OAuth.
Successful execution of the call will result is a response containing the new access token. Issue of a new access_token invalidates all old access tokens.

The “scopes” allowed by the system are:

  1. basic_read: always requested by default. Gives read access to basic information (xid, first name, last name, profile picture) which allows identification of the User.
  2. extended_read: gives read access to additional information about the user (age, gender, weight, and height). This does NOT encompass the basic_read scope.
  3. location_read: gives read access to location-related data (e.g. places where the user has eaten, etc).
  4. friends_read: gives read access to the list of XID of the user’s friends.
  5. mood_read: gives read access to mood-related data (e.g. mood.)
  6. mood_write: gives access to post a mood.
  7. move_read: gives read access to move-related data (e.g. steps, distance, etc) and workouts.
  8. move_write: gives access to create a workout.
  9. sleep_read: gives read access to sleep-related data (e.g. time to sleep, amount of deep/light sleep, etc).
  10. sleep_write: gives access to create a sleep.
  11. meal_read: gives read access to meal-related data (without location).
  12. meal_write: gives access to post a meal.
  13. weight_read: gives read access to user’s body metrics related data.
  14. weight_write: gives access to post user’s body metrics related data.
  15. generic_event_read: gives read access to user's generic events. Generic events are all user events that do not fall under an existing classification.
  16. generic_event_write: gives access to post generic events related to the user.
  17. heartrate_read: gives read access to a user's heart rate data.

The following two diagrams illustrate the authentication flow depending on where the user starts.

Installation flow from your application

This diagram provides details on the process and parameters involved when connecting a user to UP via the partner application (your app). Your app can be mobile or web based, but must use OAuth 2.0 to connect the user.

Installation flow from within the UP App

This diagram provides details on the process and parameters involved in connecting a user to a partner app from within UP. Users can find your app via their teammates feed or if your app is listed in the UP App Gallery (Jawbone invitation only). Please note the requirement to redirect back to the UP app after the OAuth flow. This is enabled by the redirect_url parameter passed to the partner app. The partner app implementation must be able to store the redirect_url and redirect the user back to the UP app after the OAuth flow.