Sunrise API Integration Guide

This document will guide you through the process of opening a connection to the Sunrise Integration API. To use this API, you will require a client ID, which your Sunrise administrator can provide. This ID is effectively your password to use the API, and so it should be well-guarded.

Authentication

To begin, you will need to obtain the authorization token from the server; this will be used as the key to authorize all future requests. Using cURL:

curl -X POST https://api.sbssunrise.com/oauth2/token \
  --data "grant_type=password&client_id=<your client ID>"

Assuming that your ID is valid, you will receive JSON similar to the following:

{
  "access_token": "<token>",
  "token_type": "bearer",
  "expires_in": 1799
}

If your ID is incorrect, you will see something like this:

{
  "error": "invalid_clientId",
  "error_description":"Invalid client_id '<your client ID>'"
}

You will need to store the access_token value for later. Keep this secure - this is like your key-card for getting into the API. Note that the expires_in value is in seconds - once the token expires, you will need to call the oauth2/token URL again to obtain a fresh token.

Once you have obtained a valid token, you can use it to authorize subsequent API calls. Using cURL:

curl -i https://api.sbssunrise.com.com/api/contacts \
  -H "Authorization: Bearer <your token>" \

Testing the API

The Sunrise API makes two methods available for checking that the API is available, and that your credentials are valid:

https://api.sbssunrise.com/api/test
https://api.sbssunrise.com/api/test/auth

The first method is designed to check that the API server is up and running - it will return HTTP 200 if so. It does not require any authorization.

The second method tests your authorization token. Using cURL:

curl -i https://api.sbssunrise.com.com/api/test/auth \
  -H "Authorization: Bearer <your token>" \

This should return:

HTTP 200 "success"

Using other technologies

The Sunrise Public API can be used with any programming or scripting language that supports HTTP. These are some sample scripts for a few of them:

JavaScript (using JQuery)

var authToken = "";
var data = { grant_type: 'password', client_id: '{{your client ID}}' };
$.getJSON("https://api.sbssunrise.com/oauth2/token", data, function (response) {
    authToken = response.access_token;

    // you can now use the auth token
    $.ajax({
        url: "https://api.sbssunrise.com/api/contacts/bob",
        type: "GET",
        headers: {
            Authorization: "bearer " + authToken
        }
    }.done(function (data) {
        // ...
    });
}).fail(function () {
    alert("Invalid client ID");
});

Powershell

Param([string]$AppId)

# get the auth token
$postParams = @{
    grant_type='password';
    client_id=$AppId
}

$result = Invoke-RestMethod -Uri "https://api.sbssunrise.com/oauth2/token" -Method Post -Body $postParams
$AuthToken = $result.access_token;

# now we can use the auth token
$headers = @{
    Authorization="bearer $AuthToken"
}

$result = Invoke-RestMethod -Uri "https://api.sbssunrise.com/api/contacts/bob" -Method Get -Headers $headers

# this will print a hash-table of contact details for 'bob'
Write-Host $result