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:

  • User

Use of the SyncTV V2 API and service requires that you do the below

  • Authorize the client application.

  • Create a user account via the Accounts API.

  • Login with the account via the user_authorize function (below).

The client application represents the device or application platform by which the service is accessed. The user account represents an individual user instance (account) in the service.

Note:
Each call to the SyncTV V2 API, with the exception of client_authorize, requires an MD5 hash signature.
See the note in user_authorize (below) for details on generating the MD5 hash signature.
Actions

Url:

  • [POST] /api/v2/authorization/user/client_authorize.[xml|json]

Client Application Authorization.

Before calling client_authorize you must first obtain a client_key for the target platform. The client key is provided by SyncTV on initial setup and configuration of the service. A unique client key is required for each platform you want to support in your service (e.g. Apple IOS, Android, etc.)

Note:
The device_uid is a unique value generated by the device/application. This value is determined by you and should be unique across all instances of the platform.
The same value should be used each time the client device/application is authorized.
Note:
The access_secret value returned by this API will be needed in subsequent calls.
The access_secret is used to generate an MD5 hash token for the purpose of validating access to the API.
Required Arguments:
  • (String) client_key
    (required) The client application's key (Provided to you by SyncTV). This key is used to determine if the application is authorized to use the service.
  • (String) device_uid
    (required) Unique identifier of the device (Made by you).
Example Request

https://service_name.synctv.com/api/v2/authorization/user/client_authorize.xml?client_key=BSHdjkf179fjkhsdfHJf894rruiaosdjKUDFkui23487&device_uid={543gdfgdg-dsfsdf453}
Example Response
XML JSON

On Success: HTTP 201
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The authorization was successful.
  code -4 (RECORD_NOT_FOUND)    The supplied client_key is not valid.

<response>
  <access_id>123</access_id>  
  <access_secret>ZqzJxppLbgtQ1JqmEzKd4DFGtepCeJdka5TBdodmeTgr</access_secret>
  <code>1</code>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>  
<response>
  <code>-4</code>
  <messages>
    <message>Record not found.</message>
  </messages>
</response>
Response Fields:
  • (Integer) access_id
    The access id required in all subsequent calls to the APIs.
  • (Integer) access_secret
    A secret value used to generate MD5 hash tokens for subsequent API calls (see user_authorize below).
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.

Url:

  • [POST] /api/v2/authorization/user/user_authorize.[xml|json]

User account authorization.

Obtaining access to the service requires that you login to a user account via this API. Prior to calling user_authorize you must first create a user account using the api/v2/accounts API.

Note:
The signature argument is an MD5 hash of alphabetically sorted URL escaped input parameters plus the access_secret value.
The access_id must be included in the list of alphabetized hashed parameters.
Note:
When computing the signature, the utf8 string passed to the service is broken down into it's component parameter and value pairs at each ampersand.
"access_id=1234&password=abcxyz&email=test@synctv.com" becomes "access_id=1234", "password=abcxyz" and "email=test@synctv.com".
Reserved characters in the parameter or value is then URL escaped, making the previous strings into "access_id=1234", "password=abcxyz" and
"email=test%40synctv.com" The url-escaped strings are then alphabetized: "access_id=1234", "email=test%40synctv.com" and "password=abcxyz".
These alphabetized strings are then combined and ampersands are added between them becoming: "access_id=1234&email=test%40synctv.com&password=abcxyz"
The access secret, for example "DSF32a5f3sdf253," is then appended to the end and the full string "access_id=1234&email=test%40synctv.com&password=abcxyzDSF32a5f3sdf253"
is hashed with MD5 to generate the signature.
Note:
URL encoding normally replaces a space with a '+' sign. Some language libraries, such as Javascript, have url-escape functions that replace '+' with '%20'.
While this is technically valid, a signature generated with this input would not be correct. Replacing all '%20' with '+' before generating the signature will solve this problem.
Note:
For example: MD5("access_id=1234&email=test%40synctv.com&password=abcxyz" + "DSF32a5f3sdf253") == b4dbc71ac4cbf1e425a33b0163be6f54
Notice the lack of an ampersand between the last param value and the access_secret. Your hash will result in signature authorization errors if you include an ampersand.
Required Arguments:
  • (Integer) access_id
    (required) Access id returned from client_authorize (see above).
  • (String) email
    (required) Email address of the account. This value is used to identify the account.
  • (String) password
    (required) Password in plain text. This value must match the password specified when creating the account.
  • (String) signature
    (required) MD5 hash encoded string of query parameters (see note).
  • (Integer) current_profile_id
    (optional) Sets the current_profile to the specified ID if the current_profile exists for this account, otherwise throws an exception.
Example Request

https://service_name.synctv.com/api/v2/authorization/user/user_authorize.xml?email=test@synctv.com&password=abcxyz&access_id=1234&signature=3909607acbc304d6c294c5f2aa4742ca
Example Response
XML JSON

On Success: HTTP 201
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The authorization was successful.
  code -5 (AUTHORIZATION_ERROR) The authorization failed. The email, password, or signature may be invalid.

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

<response>
  <code>-5</code>
  <messages>
    <message>Authorization error.</message>
  </messages>
</response>
Response Fields:
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.

Url:

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

User authorization status.

Obtaining status of authorization for current access_id. Prior to calling /status you must first create client access using /client_authorize.

Note:
The signature argument is an MD5 hash of alphabetically sorted input parameters plus the access_secret value constructed as MD5("param1=value1&param2=value2" + "access_secret").
The access_id must be included in the list of hashed parameters.
For example: MD5("access_id=1234" + "DSF32a5f3sdf253") == 3909607acbc304d6c294c5f2aa4742ca.
Required Arguments:
  • (Integer) access_id
    (required) Access id returned from client_authorize (see above).
  • (String) signature
    (required) MD5 hash encoded string of query parameters (see note).
Example Request

https://service_name.synctv.com/api/v2/authorization/user/status.xml?access_id=1234&signature=3909607acbc304d6c294c5f2aa4742ca
Example Response
XML JSON

On Success: HTTP 201
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)              The authorization was successful.
  code -5 (AUTHORIZATION_ERROR)  When there is not access with access_id or access_id is missing.

<response>
  <code>1</code>
  <access_status>0</access_status>
  <updated_at>2012-07-25T00:54:29Z</updated_at>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>

<response>
  <code>-5</code>
  <messages>
    <message>Authorization error.</message>
  </messages>
</response>
Response Fields:
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.
  • (String) access_status
    Access status depends on type of link.(e.g. 0(client) - only client access, 1(account) - account connected, -1(failed) - failed oauth2)
  • (String) access_message
    Optional field that can contain error message for OAuth2 process of authorization.

Url:

  • [POST] /api/v2/authorization/user/user_deauthorize.[xml|json]

User account deauthorization.

Obtaining access to the service and have linked account is required to do this call.

Required Arguments:
  • (Integer) access_id
    (required) Access id returned from client_authorize (see above).
  • (String) signature
    (required) MD5 hash encoded string of query parameters (see note).
Example Request

https://service_name.synctv.com/api/v2/authorization/user/user_deauthorize.xml?access_id=1234&signature=3909607acbc304d6c294c5f2aa4742ca
Example Response
XML JSON

On Success: HTTP 201
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The deauthorization was successful.
  code -5 (AUTHORIZATION_ERROR) The deauthorization failed. Incorrect access_id or incorrect signature.

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

<response>
  <code>-5</code>
  <messages>
    <message>Authorization error.</message>
  </messages>
</response>
Response Fields:
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.