Admin APIs
At its core, SyncTV is an API driven service. The APIs themselves are easy enough for developers to understand, but understanding the ecosystem is a little trickier. We've created the following tutorials to help you get your head around it.

Topics:

  • Oauth2

This document describes the client-side API for OAuth2.

Actions

Url:

  • [GET] /api/v2/authorization/oauth2/authorization_url.[xml|json]

Authorization URL

This call returns a URL to the OAuth2 provider login page. The client application should redirect the browser to this URL where the user will enter their login credentials. The browser will then be redirected to /api/v2/authorization/oauth2/callback (see below).

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of SORTED query parameters.
Example Request

[GET] https://service_name.synctv.com/api/v2/authorization/oauth2/authorization_url.xml?access_id=1&signature=sdfh2342kfs
Example Response
XML JSON

On Success: HTTP 200
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The authorization was successful.

<response>
  <authorization_url>
        http://oauth2provider.com/login?callback=http://service.synctv.com/api/v2/authorization/oauth2/callback&state=....
      </authorization_url>
  <code>1</code>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>
Response Fields:
  • (String) authorization_url
    The authorization url the client app should use to redirect the user.

Url:

  • [GET] /api/v2/authorization/oauth2/authorization_redirect.[xml|json]

Authorization Redirect

This call will redirect the Client Application using HTTP 302 header to the OAuth2 provider's login page. After entering their login credentails the user will be redirected to /api/v2/authorization/oauth2/callback (see below).

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of SORTED query parameters.
Example Request

[GET] https://service_name.synctv.com/api/v2/authorization/oauth2/authorization_redirect.xml?access_id=1&signature=sdfh2342kfs
Example Response
XML JSON

On Success: HTTP 302
On Error:   HTTP 400

Url:

  • [GET] /api/v2/authorization/oauth2/callback.[xml|json]

Authorization Callback

This is the API that user will be redirected to after successful OAuth2 authorization on the Provider website.

Note:
Authorization is not required to call this api.
Required Arguments:
  • (String) code
    OAuth2 authorization code that used in futher OAuth2 token retrieval.
  • (String) state
    Access id and secret required for preventing site forge and getting context of client access.
Example Request

[GET] https://service_name.synctv.com/api/v2/authorization/oauth2/callback.xml?state=1:wdfdsfsdf&code=BSHdjkf179fjkhsdfHJf894rruiaosdjKUDFkui23487
Example Response
XML JSON

On Success: HTTP 200
On Failure: HTTP 400

Response codes:
  code  1  (SUCCESS)               The authorization was successful.
  code  -2 (ARGUMENT_MISSING)      One or more of the required parameters is missing.
  code  -4 (RECORD_NOT_FOUND)      The access_id is invalid.
  code  -5 (AUTHORIZATION_FAILED)  OAuth2 authorization failed.

<response>
  <code>1</code>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>

<response>
  <code>-4</code>
  <messages>
    <message>Record not found.</message>
  </messages>
</response>

Url:

  • [GET] /api/v2/authorization/oauth2/status.[xml|json]

Authorization Status

The call returns the OAuth2 status for the current account.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of SORTED query parameters.
Example Request

[GET] https://service_name.synctv.com/api/v2/authorization/oauth2/status.xml
Example Response
XML JSON

On Success: HTTP 200
On Failure: HTTP 400

Response codes:
  code  1  (SUCCESS)               The authorization was successful.
  code -4  (RECORD_NOT_FOUND)      The authorization is not valid. Re-authorization is required.
  code -17  (OVER_LIMIT)      We have reached the device cap limit.

<response>
  <code>1</code>
  <status>1</status>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>

<response>
  <code>-4</code>
  <messages>
    <message>Record not found.</message>
  </messages>
</response>

<response>
  <code>-17</code>
  <messages>
    <message>Device Limit Reached.</message>
  </messages>
</response>
Response Fields:
  • (Integer) status
    Status of last OAuth2 token for the current account. Values: -1 Expired, 1 Active.