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.
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>" \
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"
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:
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");
});
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