Apps connect with CloudOS via OAuth 2.0. This is the standard used by most major API providers

Registration

Start by registering your app using the Kynetx Developer Kit (KDK) to obtain its CloudOS API credentials. The KDK is an app that can be installed by any CloudOS Developer. Be sure to use an account with a secure password to own these credentials. Since each set of credentials is tied to a particular URL, you may want to create different credentials for your development app and production app. For the purposes of OAuth, your “key” from that registration process is your “client id” here, and your secret from registering is your secret here.

Access Token

Access tokens allow apps to make requests to CloudOS on the behalf of a user. Each access token is unique to the user and consumer key. Access tokens do not expire, but they may be revoked by the user.

There are two flows for authenticating a user and obtaining an access token: code and token, which are generally used by web and client apps, respectively.

Code (Preferred)

Web server applications

Redirect users who wish to authenticate to

https://cs.kobj.net/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

If a user accepts, they will be redirected back to

    https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE

Your server will make a request for

https://cs.kobj.net/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE

The response will be JSON

{ access_token: ACCESS_TOKEN }

Save this access token for this user in your database.

In the settings for an app’s credentials, there is an option to support connecting via the web. If this option is enabled, foursquare shows a connect button on your foursquare hosted app details page, which takes the user to the first URL in the flow above and then lands the user at your registered redirect URI. If a separate account is required to use your app, you‘ll need to have the user sign-in or create that account in order to associate the foursquare token with the correct account. For example, if you use Facebook identities, the user will need to sign-in via Facebook on your landing page.

Token flow (TBD)

If you have no substantive server code, you can use the token flow outlined below

Redirect users who wish to authenticate to

https://cs.kobj.net/oauth2/authenticate
    ?client_id=CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

If a user accepts, they will be redirected back to

http://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN

Notes

For the token flow, if your app is pure Javascript, you can easily parse the token from the URL. If your app is a native phone app then perform the flow in an embedded webview, redirecting the user to a dummy website. You can then grab the token off of the URL and close the browser. We have sample Android and iOS code for your reference.

PLEASE take steps to obfuscate your client secret if you include it in released code; be prepared to rotate it if needed.

If register multiple redirect URIs for your app, you can specify which URI to use by changing the value of the redirect_uri parameter. If you enable web connect, your users will be redirected to your first redirect URI.

Requests

Once you have an access token. It’s easy to use any of the Sky Cloud endpoints.

The preferred method for sending the access token along with the request is to pass it as the value for the header 'Kobj-Session', but you can also add oauth_token=ACCESS_TOKEN to your GET or POST request. For example, from the command line, you can do either

curl --header "Kobj-Session: ACCESS_TOKEN" https://cs.kobj.net/sky/cloud/a16x55/get_temperature?room=bedroom (Preferred)

curl https://cs.kobj.net/sky/cloud/a16x55/get_temperature?room=bedroom&oauth_token=ACCESS_TOKEN

That’s all there is to it.

We encourage web apps to use session cookies to verify a user's identity once the user has been initially authenticated. All embedded webviews inside of foursquare share the same cookies, so all subsequent interactions can rely on the session cookie to authenticate the user, avoiding server redirects each time the user interacts with the app.

Attribution

This page is modeled closely after the FourSquare Connecting page because it is a model of clearly showing how OAuth works with their service.

developer

Connecting (Authorizing your CloudOS Client Application)