Accessing the dSS

The dSS is accessible through a HTTP based JSON interface.
External applications accessing the dSS must not store any passwords at any time. Instead they should request an application-token which has to be activated by the user.

Getting a token

An application needs to get and store an application token from the dSS:

https://yourdss:8080/json/system/requestApplicationToken?applicationName=readable%20Name%20of%20application

Note that when requesting an application token, the application must not be logged in with username/password or access the dSS through the default HTTPS port.

Approving the token

Once the token is retrieved and stored, it can be activated from the dSS Web Interface in Advanced -> System -> Access Control.

Alternatively, the token can be approved from the application by asking the user for dSS username/password and use this to login:

https://yourdss:8080/json/system/login?user=dssadmin&password=mysupersecretpassword

This returns a temporary session token, which can be used to enable the application token using this command:

https://yourdss:8080/json/system/enableToken?applicationToken=the_application_token&token=the_temporary_session_token

Logging in

After the token has been approved the application may obtain a session-token by providing the application token:

https://yourdss:8080/json/system/loginApplication?loginToken=yourtokenhere

Using the session token

Add the token to the http header, or add "token=yoursessiontokenhere", fx:

https://yourdss:8080/json/apartment/getStructure?token=yourtokenhere

The session token has a timeout of 60 seconds, but will be prolonged each time it is used/touched.
If the session token is invalid, a new session token should be acquired.

Self signed certificate

The dSS uses a self signed certificate, so in order to connect the user should accept that the certificate is not signed by a known authority.
This can also be solved by simply accepting any certificate in your network client.

Slideshow

Attached is a slideshow explaining the JSON API access and the login process.

Making crosssite browser requests

Every request takes an additional callback parameter that will wrap the JSON answer. This allows browsers to fetch data from another host than the website is running on.
Example:
Fetch with

<script src="https://yourdss:8080/json/apartment/getStructure?token=yourtokenhere&callback=foo" type="text/javascript"></script>

The answer will then look like
foo({"result":"ok", ... })

Thereby calling your foo function, so make sure it is available at the time the request is made.
This feature is available in all dSS versions new than - but excluding - 1.18.0

smartphone_digitalstrom.pdf (370 KB) Lasse Hansen, 05/30/2012 04:13 PM