API Documentation

This page describes the APIs necessary to write applications that are GOL/ROL aware.  Please read the  Syncplicity Architecture before proceeding with this page.

OAuth Authentication

In general, the OAuth authentication mechanism is the same in the ROL and non-ROL use-cases. No code needs to change for the existing applications that were using the existing US API gateway api.syncplicity.com. However, in the case where a developer does want an application to invoke APIs on multiple ROLs, then it will be necessary to enhance the application in a few key areas.

  • ApplicationKey/ApplicationSecret: The application being developed can use the same pair of ApplicationKey/ApplicationSecret for any ROL access through the API gateway. When you allocate a new ApplicationKey/ApplicationSecret in the developer portal, the ApplicationKey/ApplicationSecret are stored in all API gateways regardless of what ROL is being access, so as a developer you only need to track one pair of keys/secrets per application. NOTE: pre-existing ApplicationKey/ApplicationSecret that were defined pre-ROL/GOL awareness, will also have been updated in all the API gateways.
     
  • Bearer token: The bearer token returned from the initial OAuth login to the home ROL is valid on all ROLs, but the application must perform the initial OAuth authentication to only the home ROL, if another ROL is used for login/authentication the application will receive an authentication error and will not be able to proceed. There is a distinction when the application must access the Personal Identifiable Information (PII) service of a foreign ROL, however; due to privacy reasons, a one-time bearer token will be allocated for access PII information on a foreign ROL. See more details in the PII service documentation below.
     
  • Refresh token: refresh token can be used only with home ROL used for the initial authentication
     
  • Revoke token: the revoke token call can only be submitted against the can be used only with issued ROL

 

ROLs Get

This is an unauthenticated API call to the GOL that resolves the list of ROLs that a given user has access to. The response is an array of ROLs with additional metadata informing which is the home ROL for the given user and what api gateway host name should be used to invoke API calls on that ROL.

 

Resource URL

https://gol.syncplicity.com/api/v1/rols?uhid={user_email_hash}

 

URL Parameters

Param Name Required Description Data Type Valid Values
uhid={user_email_hash} Yes If specified, retrieves the storage endpoint (StorageVault) definitions of the specified user; otherwise, the current user of the application is used. String User email hash is calculated using the user's email and encoding it using the HMac MD5 algorithm with "6adebb9f-21f9-49d8-95bf-b7007a208cd4" salt.

 

HTTP Header Parameters

Name Value Description
Accept
(required)
application/json Accept type of the request

 

Personal Identifiable Information (PII)

To ensure clarity, an application can only look up PII information that they're authorized to see such as through a Syncpoint or file share between users of different ROLs. If the application’s privilege’s include accessing the participants of a particular Syncpoint or file-share then the application is authorized to look up the PII information of that user such as their name and email. No other personal information can be found for any unauthorized access.

For functional reasons, it may be necessary for the application to look up personal information that is stored in a different ROL. As an example, the Syncpoint-Participants API can return a list of users that participate in a given Syncpoint and one or more of these users may reside in a different home ROL from the application’s. In this scenario, the foreign user’s name and email will not be included in the response, instead a user id is the only metadata returned for these types of users. Programatically, an application can know that a particular user is from a foreign ROL by inspecting the OrgininalRolId field of the various API responses, if the OrgininalRolId value differs from the application’s home ROL id, then the application knows which foreign ROL the user’s PII resides.

If the application logic requires the PII information, the application must call the home ROL PII service with the user Ids to generate a one-time use bearer token that will be authorized to call the PII service of the foreign ROL to look up the user’s name and email.

Below is a diagram that shows how the application may need to look up PII related data from a foreign ROL for the use-case mentioned above.

Example response from the syncpoint participants (See syncpoints participants documentation above for full API documentation).
•    EmailAddress is empty string
•    OriginalRolId differs from current ROL

 

Sample JSON Response

[
  {
    "User": {
      "EmailAddress": "someuser@dispostable.com",
      "FirstName": "someName",
      "LastName": "someLastName"
    },
    "Permission": 1,
    "Mapped": true,
    "IsOwner": true,
    "IsExplicit": true
  },
  {
    "User": {
      "Id": "bbe998e2-e759-495b-897e-6afaa76bb8c0",
      "EmailAddress": "",
      "FirstName": "",
      "LastName": "",
      "OriginalRolId": 2
    },
    "Inviter": {
      "Id": "e3938cb5-e985-4fb1-be37-b4f2c8891477",
      "EmailAddress": "someuser@dispostable.com",
      "FirstName": "someName",
      "LastName": "someLastName"
    },
    "Permission": 1,
    "Mapped": false,
    "ResharingAllowed": false,
    "ParticipantResharingPolicy": 3,
    "IsExplicit": true
  }
]

 

Users PII GET

This API resolves the user GUIDs for the specified set of users into the PII related data for those users including First Name, Last Name and Email.

The API will provide results in the following use cases otherwise the call is considered unauthorized and will return an error:

  • The application is sending the GUID of the currently authenticated user
  • The application is authenticated as a Business Admin and the GUID represents a user which is a member of the company
  • The application is authenticated a user that has shared a Syncpoint with a recipient that resides in the ROL being invoked and the GUID represents the Syncpoint participant residing in that ROL

If the PII service is invoked with a user GUID that is not a member of the ROL associated with the PII service call, but the application is authorized to view the PII information of the specified user, then the PII service will return a bearer token for the foreign ROL PII service to look up the PII information of the specified user in the foreign ROL PII service. This is a required step to look up PII related information for a user associated with a foreign ROL, the application must look up the bearer token in the application’s home ROL PII service first, then make the remote ROL PII service call using the new bearer token.

 

Resource URL

https://{ROL host name}/rol/users_pii.svc

 

HTTP Header Parameters

Name Value Description
AppKey   Consumer Key of the app from Developer Portal. Note this must be
specifically assigned to the ROL being invoked.
Authorization Bearer <value>  Authorization token
Content-Type application/json The Content-Type of the request
Accept application/json Accept type of the request

 

Sample JSON Input

[
    "<user_guid_1>",
    "<user_guid_2>",
    ...
    "<user_guid_N>",

]

 

Sample JSON Input Definition

Accepts array of user GUIDs that will be processed and the service will return the PII data for each associated GUID. Invalid GUIDs will be ignored with no error response.

Field Description Data Type
Array Array of user GUIDs JSON Array

 

Sample JSON Response

{
   "RolUserPIIs":[
      {
         "Users":[
            {
               "Id":"64443e0b-1e02-4b20-a27a-0d0d82cfaef7",
               "EmailAddress":"some@email.com",
               "FirstName":"somefirstname",
               "LastName":"somelastname"
            },
            {
               "Id":"e39a3628-e786-4918-9715-5228e637d87d",
               "EmailAddress":"someanother@email.com",
               "FirstName":"A",
               "LastName":"B"
            }
         ],
         "HomeRolId":1,
         "Bearer":""
      },
      {
         "Users":[
            {
               "Id":"e07c1f35-7264-47a9-892b-08b1a3706c7a"
            },
            {
               "Id":"62477cbd-5a1d-4ebb-9cca-ebd69aa70276"
            }
         ],
         "HomeRolId":2,
         "Bearer":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"
      },
      {
         "Users":[
            {
               "Id":"166d8d52-e4fa-4444-9ae4-dd067346f504"
            }
         ],
         "HomeRolId":3,
         "Bearer":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"
      }
   ]
}

 

Sample JSON Response Definitions

Field Description Data Type
RolUserPIIs JSON object encapsulating all returns users.  

Each sub-section of grouped users is grouped by the home ROL of the resulting users.

JSON Object
RolUserPIIs.Users  Array of users with personal information inside  Array
RolUserPIIs.Users.Id The guid of the returned user GUID
RolUserPIIs.Users.EmailAddress The email of the user if known on the current ROL String
RolUserPIIs.Users.FirstName The first name of the user if known on the current ROL String
RolUserPIIs.Users.LastName The first name of the user if known on the current ROL String
RolUserPIIs.HomeRolId The ID of the home ROL of the related users String
RolUserPIIs.Bearer One time use short-lived bearer token for invoking the PII service of the user’s home ROL, if the associated users have a different home ROL from the current one. String

 

Response Error Details

HTTP Code Error Code Description
403 Forbidden Unauthorized to call this API
400 Bad request User Ids Must Be Set, when there is no any user id in the list