OAuth2 API

Suripu provides an OAuth2 API.

Authentication

Official Hello apps

Official Hello apps will use the username-password flow for authenticating with the suripu API. If you’re unfamiliar with this flow, check out this helpful Salesforce guide but basically it means you log in with your username and password and you get an oauth access token in exchange.

3rd party apps

3rd party apps will have to use the Oauth code flow, where they are granted a temporary code and redirected to a registered URL. This Oauth is not yet implemented.

What’s an oauth access token?

An access token is more or less a secret, shared between the client (mobile app) and the server for authenticating requests. It's a random string, something like this: 3a2bf378def149289ca50c90a9099e7a

In the future, access tokens will contain the ID of the application registered with that token. Ex: 123.3a2bf378def149289ca50c90a9099e7a where 123 is the application ID and 3a2bf378def149289ca50c90a9099e7a the secret.

When the access_token is generated, the JSON response contains a generated_at * and expires_in attribute.

NOT IMPLEMENTED: The generated_at attribute is purely for clients to measure clock skew between them and the server.

The expires_in defines the TTL of the token in seconds.

Important: in the username-password flow, no refresh_token is issued. If the token is compromised, or if the session expires, the user will have to log in again.

Typically, a access token response looks like this:

{
    "token_type" : "Bearer",
    "expires_in": 7776000,
    "access_token" : "6cb8e60578ae4e34af7feddfb8690722",
    "refresh_token" : ""
}

The url for obtaining an access token follows the following pattern. http://api.domain.tld/oauth2/token

nb: a version number should either be added to the subdomain api-v1.host.domain.tld or the the path http://api.domain.tld/v1/oauth2/token

Calls to the API should then include the token in a header

* Connected to api.domain.tld (88.88.88.88) port 80 (#0)
> GET /account HTTP/1.1
> User-Agent: curl/7.30.0
> Host: api.skeletor.com
> Accept: */*
> Authorization: Bearer 3a2bf378def149289ca50c90a9099e7a

Application registration

To be granted API access, you need to register an application.

{
  "name": "Test OAuth Application",
  "client_id": "123456",
  "client_secret": "654321ClientSecret",
  "redirect_uri": "http://hello.com/oauth",
  "scopes": [
    "USER_BASIC",
    "USER_EXTENDED",
    "SENSORS_BASIC",
    "SENSORS_EXTENDED"
  ],
  "dev_account_id": 1,
  "description": "Official Hello Application"
}

Scopes

At the moment 19 scopes are available:

1. USER_BASIC, which grants basic access to a user's profile (name, timezone, etc.)
2. USER_EXTENDED which grants access to all information about a user (USER_BASIC + age, weight, height, etc.)
3. SENSORS_BASIC which grants access to the basic sensors (humidity, temperature, air quality)
4. SENSORS_EXTENDED which grants access to all sensor data (SENSORS_BASIC + sound, gps, etc)
5. SENSORS_WRITE which grants access to collecting sensor data (for now official apps only)
6. SCORE_READ
7. SLEEP_LABEL_BASIC
8. SLEEP_LABEL_WRITE,
9. ADMINISTRATION_READ
10. ADMINISTRATION_WRITE
11. API_INTERNAL_DATA_READ
12. API_INTERNAL_DATA_WRITE
13. SLEEP_TIMELINE
14. QUESTIONS_READ
15. QUESTIONS_WRITE
16. FIRMWARE_UPDATE
17. ALARM_READ
18. ALARM_WRITE
19. PUSH_NOTIFICATIONS

Endpoints

Currently the supported endpoints are:

    DELETE  /v1/oauth2/token
    GET     /v1/oauth2/authorize
    POST    /v1/oauth2/token
    GET     /v1/account
    POST    /v1/account
    POST    /v1/account/password
    PUT     /v1/account
    GET     /v1/history/motion
    GET     /v1/history/sound
    GET     /v1/applications
    GET     /v1/applications/{dev_account_id}
    POST    /v1/applications
    GET     /v1/sleep/get
    POST    /v1/sleep/save
    GET     /v1/room/admin/{sensor}/day
    GET     /v1/room/current
    GET     /v1/room/{sensor}/day
    GET     /v1/room/{sensor}/week
    GET     /v1/room/{sensor}/{device_name}/day
    GET     /v1/events/{target_date_string}
    POST    /v1/events
    POST    /v1/devices/pill
    GET     /v1/timeline/{date}
    DELETE  /v1/notifications/registration
    POST    /v1/notifications/registration
    GET     /v1/questions
    POST    /v1/questions
    GET     /version
    GET     /ping

As the API is still in draft mode, the response from these endpoints can/will change. The Content-Type headers will always be set to application/json