Skip to content

Integrations

Jump to bottom Edit New page
Wojciech Frącz edited this page Nov 13, 2019 · 8 revisions

API documentation

Every SUPLA Cloud instance has its own interactive API documentation available at /api-docs URL. You will find link to these docs on My Account -> Integrations -> My OAuth apps page.

Use OAuth Apps if you want to integrate your application with SUPLA and want to share it with others in a comfortable way.

For personal use of API (e.g. scripts or some DIY solutions), the Personal Access Tokens might be an easier choice.

OAuth Apps

SUPLA Cloud API implements OAuth2 authorization-code flow.

OAuth apps allow to leverage SUPLA Cloud API. Every user that wants to use your app will be asked to authorize it. Provided that access has been granted by the user, your app will be given an authCode that you will use to issue an access token for the given user. Depending on the scope you ask for during the authorization, the token can be used to call different API endpoints.

OAuth URLs for official SUPLA Cloud for public applications:

  • Authorization URL: https://cloud.supla.org/oauth/v2/auth
  • Token URL: https://cloud.supla.org/oauth/v2/token

The access tokens are issued for approx 1 hour. In order to refresh the token without repeated user authorization, your app should ask for offline access scope and then use the refresh token flow to gain a new access and refresh token for that user. Refresh tokens are valid for approx 30 days.

Local OAuth Apps

By default, the OAuth app you create in your account is local, i.e. is accessible only on the server that you have your account on. It may be either one of our official svrX.supla.org instances or your private server. In order to authenticate private application, you must point the authorization URL directly to the instance, e.g.:

  • Authorization URL: https://svr3.supla.org/oauth/v2/auth or https://yoursupla.yourraspberry.com/oauth/v2/auth
  • Token URL: https://svr3.supla.org/oauth/v2/token or https://yoursupla.yourraspberry.com/oauth/v2/token

The rest of the flow stays the same.

Public OAuth apps

OAuth apps can be made public, i.e. available in the apps catalog. Such apps can be used in any SUPLA Cloud instance: official one and registered private SUPLA Clouds. Apps catalog is available at https://cloud.supla.org/apps. If you want your application to be public and available for anyone, feel free to contact us with the application details and purpose. You will find the contact details at https://supla.org.

Registering your private SUPLA Cloud

Go to https://cloud.supla.org/register-cloud and register your instance with the instructions there.

Personal Access Tokens

Personal access tokens can be issued in the My Account -> Integrations -> Personal access tokens page. The token can be used in the same way as it would if issued by the OAuth2 flow. The main difference is that they never expire so it's very important to keep track of them and delete unused tokens as soon as you don't need them. The personal access token gives access to all of the selected scopes that you select when you create it.

Token structure

Every SUPLA Cloud API token has two parts separated by dot . character. The first part is a randomized string. The second part contains a base64-encoded URL address of the target API. This is because the official https://cloud.supla.org acts only as a broker for real target SUPLA Clouds (either official or private). Therefore, when communicating with the API you must point your requests directly to the issuer instance, not to the cloud.supla.org because your token will be rejected there even if it's valid.

Example token:

MjJjY2M2ZGZjZWZmZmUwZTM2ZDJlOTA1MDcxMTE4YjYwNTk5ODQ4ZDZmZjQyYTM0NzY3ZDBhODQzOTBmNDkwZg.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw==

If you decode the URL part, you will find out that it has been issued by the https://svr3.supla.org and this is the target SUPLA Cloud that will recognize it and allow its access.

Keep in mind that the OAuth2 flow always uses the https://cloud.supla.org for issuing and refreshing access tokens for public apps, regardles of the target SUPLA Cloud. This is achieved by implementing an [OAuth SUPLA Broker Workflow] (https://github.com/SUPLA/supla-cloud/wiki/OAuth-SUPLA-Broker-workflow) The encoded target URL should be used only after the access has been granted by cloud.supla.org.

Token usage

The token should be sent in the Authorization header with a Bearer scheme. Example:

Authorization: Bearer MjJjY2M2ZGZjZWZmZmUwZTM2ZDJlOTA1MDcxMTE4YjYwNTk5ODQ4ZDZmZjQyYTM0NzY3ZDBhODQzOTBmNDkwZg.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw==

cURL (command line) example:

curl https://svr3.supla.org/api/users/current -X GET -H "Authorization: Bearer MjJjY2M2ZGZjZWZmZmUwZTM2ZDJlOTA1MDcxMTE4YjYwNTk5ODQ4ZDZmZjQyYTM0NzY3ZDBhODQzOTBmNDkwZg.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw=="

Example OAuth flow

We assume you have an OAuth app and you know its clientId 1_abc and secret XYZ and that the redirect URI used for authorization is https://your-app.com/authorize.

  1. You choose the required scopes you need to have in order for your integration to work correctly. Here we ask for account_r iodevices_r channels_ea channels_r offline_access. You prepare a button in your application (Authorize or something like that) that takes your users to the SUPLA Authorization URL. As per OAuth2 flow, the state parameter can be used by your application to identify the authorization request.

  • if your app is public:

    https://cloud.supla.org/oauth/v2/auth?client_id=1_abc&redirect_uri=https://your-app.com/authorize&state=123&response_type=code&scope=account_r%20iodevices_r%20channels_ea%20channels_r%20offline_access

  • if not, you should use your server host instead:

    https://yoursupla.yourraspberry.com/oauth/v2/auth?client_id=1_abc&redirect_uri=https://your-app.com/authorize&state=123&response_type=code&scope=account_r%20iodevices_r%20channels_ea%20channels_r%20offline_access

  1. In either way, the user will see an authentication form

    And then, authorization form for your application and the scopes you have requested for.

  2. When user grants access to your account, they are being redirected back to your redirect URI, passing and code and state parameters. Example redirection URL:

    https://your-app.com/authorize?code=Yjc4OTc5MTUxNDQ4NjhhYmUxNGI5YThmY2M0MWFiYTdhOTJlMzVhODA0MjU3YTBiNTEwZGQzYWVjMGQ1ZDBjZQ.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw%3D%3D&state=123

  3. When your app receives the auth code, you want to use it immediately to issue an access token (and refresh token, if you asked for offline_access scope). The given authorization code is valid for approx 30 seconds only. Therefore, your application, should query the SUPLA Cloud back with given auth code and app's secret to obtain a new access token for the user. The request should be a POST to https://cloud.supla.org/oauth/v2/token (or your server URL for local OAuth apps) with the ContentType: application/json header and the following body:

    {
  "grant_type": "authorization_code",
  "client_id": "1_abc",
  "client_secret": "XYZ",
  "redirect_uri": "https://your-app.com/authorize",
  "code": "Yjc4OTc5MTUxNDQ4NjhhYmUxNGI5YThmY2M0MWFiYTdhOTJlMzVhODA0MjU3YTBiNTEwZGQzYWVjMGQ1ZDBjZQ.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw=="
}

  4. If everything is ok, SUPLA Cloud responds you with the new user access token:

    {
  "access_token": "ZmFmNDk5OThkYjQ1N2I5ZmQxMmY4NzAxYTNlZjRjMDc4MTRiN2E3MmQwMWJmYjlmZGJlN2I1Y2RhMjQyYTc4MQ.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw==",
  "refresh_token": "YmFlODViYmVkMDFkMGUyNGRhYWMzNTY3MTAyOWY1ZjU5MzBlZmIyYWQyYTU3M2IyOWM5ZDg4NjdjZTQ4NTJlMQ.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw==",
  "expires_in": 3610,
  "token_type": "bearer",
  "scope": "account_r iodevices_r channels_ea channels_r offline_access",
  "target_url": "https://svr3.supla.org"
}

    It's good idea to verify now, if the granted scopes are the same as you asked for, as users can manipulate the authorization URLs. The target_url is the same as encoded inside the token and is passed here only for your convenience.

  5. Now, the obtained access token and (possibly) refresh token should be stored in your app. It may interact with the SUPLA Cloud API on behalf of the user that has granted access for your application by providing an approriate Authorization header to all requests (see above).

  6. If the access token is about to expire or if it has been expired (you hit 401 API Error), your app may want to refresh the token with the refresh token provided. In order to do so, execute a POST request to https://cloud.supla.org/oauth/v2/token (or your server URL for local OAuth apps) with the ContentType: application/json header and the following body:

    {
  "grant_type": "refresh_token",
  "client_id": "1_abc",
  "client_secret": "XYZ",
  "refresh_token": "YmFlODViYmVkMDFkMGUyNGRhYWMzNTY3MTAyOWY1ZjU5MzBlZmIyYWQyYTU3M2IyOWM5ZDg4NjdjZTQ4NTJlMQ.aHR0cHM6Ly9zdnIzLnN1cGxhLm9yZw=="
}

    The response for such request is the same as for issuing the token with the authorization code.

If a user has already granted your application before and you ask for the same scopes with the authorization URL (point 1), user will be immediately redirected back to your application after authenticating in SUPLA Cloud (without authorization form). However, if you need to change the scopes (i.e. ask for more access), your users must reauthorize your by repeating the authorization process.

Add a custom footer
Add a custom sidebar
Clone this wiki locally