OAuth

Aus smart-me
Wechseln zu: Navigation, Suche

smart-me supports the authorization framework OAuth 2.0. External applications can apply for access to an account without having to know the login credentials.

Detailed information regarding roles, protocol flow, authorization, endpoints and tokens can be found at https://tools.ietf.org/html/rfc6749 In order to use the OAuth interface, a client ID and a client secret is required. If you do not have either a client ID or a client secret, please contact us.

Grants

smart-me supports two authorization grant types:

  • The implicit grant flow (Recommended if you are building a Webapp or Microapp)
  • The authorization code grant flow (Recommended for long term API access)


Implicit Grant

Is to be used, when the OAuth client is implemented in a browser using a scripting language such as JavaScript. Choose this if you are building a Webapp or a Microapp. Since invalid or expired access tokens cannot be refreshed with the the implicit grant type, this should only be used for widgets that are displayed for a limited amount of time, e.g. one-off usage.

1. Authorization

When the user wants to use the 3rd-party application (i.e. a widget), they must be redirected to the authorisation endpoint first:

https://api.smart-me.com/api/oauth/authorize

client_id Will be provided by smart-me. (example: myapp)
response_type token
redirect_uri The widget URL, e.g. https://www.example.com
scope Specifies the scope of the access (e.g. device.read)
state Value used by the client to maintain state between the request and callback (for example an urlencoded json object)

Example

https://api.smart-me.com/api/oauth/authorize?client_id=myapp&response_type=token&redirect_uri=https%3A%2F%2Fwww.example.com&scope=device.read&state=mystate

If the user is not already logged into the app, they are redirected to a login form.

Oauth login as.jpg

After the user is authenticated, smart-me prompts the user to authorize your widget to access their data. The user can accept or decline your app and also define the scope of data access for your widget.

Oauth grant.jpg

When the authorization succeeded, the user gets redirected to the redirect_uri with the access token as URI fragment: https://example.com#access_token=aaaaaa&expires_in=3600&token_type=bearer&state=mystate

2. Do API calls

Your app can then use the access_token to authorize calls to the API by sending it as Authorization HTTP header:

Authorization: Bearer <access_token>

Expired access token

When the access_token expires, the whole widget has to be reloaded to restart the authorization flow.


Authorization Code Grant

Is to be used when a server acts as OAuth2 client and the client should have a long term API access on behalf of the user. Invalid or expired access tokens can be refreshed.

Flow

You need to execute the following five steps to create an API request:

  1. Request authorization
  2. smart-me redirects the user to the authorization page
  3. Request an access token
  4. Receive the access token
  5. Make API calls


1. Authorization

When the user wants to use the 3rd-party application (i.e. a custom App), they get redirected to the authorisation endpoint first:

https://api.smart-me.com/api/oauth/authorize

client_id Will be provided by smart-me. (example: myapp)
response_type code
redirect_uri The App URL, e.g. https://www.example.com
scope Specifies the scope of the access (e.g. device.read)
state Value used by the client to maintain state between the request and callback (for example an urlencoded json object)

Example

https://api.smart-me.com/api/oauth/authorize?client_id=myapp?client_secret=mysecret&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.com&scope=device.read&state=mystate

After the user is authenticated, smart-me prompts the user to authorize your App to access their data.

Oauth login as.jpg

The user can accept or decline your app and also define the scope of data access for your App.

Oauth grant.jpg

2. Exchange auth code

When the authorization succeeded, the user gets redirected to the redirect_uri with an auth code appended as code query parameter:

https://www.example.com/?code=mycode&state=mystate

Your app will have to use the auth code to request an access_token by sending a POST request to the token endpoint:

https://api.smart-me.com/api/token/

client_id Will be provided by smart-me. (example: myapp)
client_secret Will be provided by smart-me. (example: mysecret)
response_type authorization_code
code The auth code (mycode in the example)
redirect_uri The App URL, e.g. https://www.example.com

POST https://api.smart-me.com/api/oauth/token client_id=myclient&client_secret=mysecret&grant_type=authorization_code&code=mycode&redirect_uri=https%3A%2F%2Fwww.example.com

The form data fields need to be encoded as content type application/x-www-form-urlencoded.

The response contains an access_token and a refresh_token. The access_token can then be used to make api calls on behalf of the user, while the refresh_token can be used to retrieve a new access_token.

Response

{
  "access_token": "mytoken",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": "device.read",
  "refresh_token": "myrefreshtoken"
}

3. Do API calls

Your app can then use the access_token to authorize calls to the API by sending it as Authorization HTTP header:

Authorization: Bearer <access_token>


4. Refreshing expired access token

When the access_token has expired (the lifetime is 3600 seconds) or becomes invalid, you have to use the refresh_token to request a new access_token by sending a POST request to the token endpoint:

https://api.smart-me.com/api/token/

The required form data to refresh the access_token:

client_id Will be provided by smart-me. (example: myapp)
client_secret Will be provided by smart-me. (example: mysecret)
response_type refresh_token
refresh_token The refresh_token, (myrefreshtoken in the example)

POST https://api.smart-me.com/api/oauth/token client_id=myclient&client_secret=mysecret&grant_type=refresh_token&refresh_token=myrefreshtoken

The response contains an access_token and a refresh_token. The access_token can then be used to make api calls on behalf of the user, while the refresh_token can be used to retrieve a new access_token.

Response

{
  "access_token": "mytoken",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": "device.read",
  "refresh_token": "myrefreshtoken"
}