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:

  • Xbox

Use of the SyncTV V2 API requires that you first authorize the client device. XBox devices require a special authorization process which varies from the normal user authorization process. The xbox/v1_authorize API authorizes an XBox device using an XBox Live SAML (certificate) which contains device identifying information. The xbox/v1_deauthorize API can be used to deauthorize an XBox device.

Note:
This XBox authorization API will be deprecated in a future release.
Actions

Url:

  • [POST] /api/v2/authorization/xbox/v1_authorize.[xml|json]
Note:
For proper post request parsing, add http header to the request: Content-type: application/x-www-form-urlencoded
Required Arguments:
  • (String) client_key
    (required) Key for the client XBox. This key is used to determine if the XBox is authorized to use the service.
  • (String) 'XBL2.0 x'
    (required) Encrypted SAML from the device
Example Request

The following example requests an authorization token for an account that is already linked to the XBox device.
[POST] https://service_name.synctv.com/api/v2/authorization/xbox/v1_authorize.xml?client_key=BSHdjkf179fjkhsdfHJf894rruiaosdjKUDFkui23487

The following example links an account to a device.
[POST] https://service_name.synctv.com/api/v2/authorization/xbox/v1_authorize.xml?email=example@synctv.com&password=123456&client_key=BSHdjkf179fjkhsdfHJf894rruiaosdjKUDFkui23487
Example Response
XML JSON

On Success: HTTP 200
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The authorization was successful.
  code -2 (ARGUMENT_MISSING)    When `XBL2.0 x` argument missing in post body
  code -4 (RECORD_NOT_FOUND)    Client key is invalid.
  code -6 (SAML_ERROR)          The SAML is invalid or user information can't be extructed from SAML body.

<response>
  <account>
    <id>100</id>
    <email>example@synctv.com</email>
  </account>
  <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) [account]id
    The id of the user account linked to the device.
  • (Integer) [account]email
    The email of the user account linked to the device.
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.

Url:

  • [POST] /api/v2/authorization/xbox/v1_deauthorize.[xml|json]

Xbox v1 Deauthorization

Note:
Deuthorization requires that the authorization token, returned in xbox/v1_authorize, is passed in the HTTP request header as tag 'AUTHORIZATION'.
Required Arguments:
  • (String) AUTHORIZATION
    (required) Authorization token passed in the HTTP request header in the form of ['AUTHORIZATION']=12345 (see note)
Example Request

The following example deauthorizes the currently authorized XBox account.
[POST] https://service_name.synctv.com/api/v2/authorization/xbox/v1_deauthorize.xml
Example Response
XML JSON

On Success: HTTP 200
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The deauthorization was successful.
  code -2 (ARGUMENT_MISSING)    The AUTHORIZATION header was not provided.
  code -4 (RECORD_NOT_FOUND)    There is no record that matches the supplied authorization token.
  code -5 (AUTHORIZATION_ERROR) The supplied authorization token is invalid.

<response>
  <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) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.

Url:

  • [POST] /api/v2/authorization/xbox/authorize.[xml|json]

Xbox Authorization

Before calling authorize, you must first obtain a client_key for the target XBox platform. The client key is provided by SyncTV on initial setup and configuration of the service.

Required Arguments:
  • (String) client_key
    (required) Key for the client XBox. This key is used to determine if the XBox is authorized to use the service.
  • (String) 'XBL2.0 x'
    (required) Encrypted SAML from the device
  • (String) 'XBL3.0 x'
    (required) JWE from the device
Example Request

The following example requests an authorization token for an account that is already linked to the XBox device.
[POST] https://service_name.synctv.com/api/v2/authorization/xbox/authorize.xml?client_key=BSHdjkf179fjkhsdfHJf894rruiaosdjKUDFkui23487
Example Response
XML JSON

On Success: HTTP 200
On Error:   HTTP 400

Response codes:
  code  1 (SUCCESS)             The authorization was successful.
  code -2 (ARGUMENT_MISSING)    When `XBL2.0 x` argument missing in post body or XBox user is not connected and email or password wasn't provided
  code -4 (RECORD_NOT_FOUND)    Client key is can't be found.
  code -5 (AUTHORIZATION_ERROR) When account with such email not found, or password is invalid
  code -6 (SAML_ERROR)          The SAML is invalid or user information can't be extructed from SAML body.

<response>
  <access_id>123</access_id>
  <access_secret>ZqzJxppLbgtQ1JqmEzKd4DFGtepCeJdka5TBdodmeTgr</access_secret>
  <account>
    <id>100</id>
    <email>example@synctv.com</email>
  </account>
  <profile>
    <id>1</id>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
  </profile>
  <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.
  • (Integer) account[id]
    The id of the user account linked to the device.
  • (Integer) account[email]
    The email of the user account linked to the device.
  • (Integer) profile[id]
    The unique identifier of the profile.
  • (String) profile[first_name]
    The first name attached to the profile.
  • (String) profile[last_name]
    The last name attached to the profile.
  • (Integer) code
    Result code (see response codes above).
  • (String) message
    Response message(s) based on result code.

Url:

  • [POST] /api/v2/authorization/xbox/deauthorize.[xml|json]

Xbox Deauthorization

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:
Caveat: URL encoding normally replaces a space with a '+' sign. In some language libraries (like Javascript) url-escaped functions swaps out '+' with '%20',
which is a technically valid, however this leads to an incorrectly generated signature. Solution: gsub '%20' with '+' before MD5 is performed.
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 Xbox Authorization.
  • (String) signature
    (required) MD5 hash encoded string of alphabetically sorted query parameters.
Example Request

The following example deauthorizes and XBox account on the service.
[POST] https://service_name.synctv.com/api/v2/authorization/xbox/deauthorize.xml?access_id=324&signature=ca88c851c1e9810aad563106975bfcdf
Example Response
XML JSON

On Success: HTTP 200
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.