API Documentation

Syncplicity Architecture


The following graphic illustrates the core architectural components of the Syncplicity application programming interfaces (APIs). Also represented are the primary interactions between the components and third-party applications.

This topic provides details about the following key parts of the graphic.

  • Syncplicity supports a hybrid cloud approach. This means a customer might use both Syncplicity public cloud and their own private clouds. For application developers there is no single Uniform Resource Locator (URL) to use when downloading and uploading files. The URLs should be discovered for each root folder (syncpoint) via special API call.
  • Syncplicity supports multi-data center architecture. Syncplicity users can belong to different data centers. However, a single tenant (company) with all its users might belong to only one as its home. It remains valid to share files between Syncplicity users in different data centers. Application developers must discover the data center a Syncplicity user belongs to and use the API gateway in that data center to access user information. This discovery can be done via a special public service in the global orchestration layer (GOL).
  • Some private cloud installations can have an additional layer of security called storage vault authentication (SVA). When enabled, a private cloud storage connector service does not accept an Open Authentication 2 (OAuth 2) access token as the only claim that allows accessing file content. It also requires a user to authenticate via the browser on the storage connector node. As a result, it issues an SVA cookie or token that should not leave the premises of the user client device. For application developers, this means server-side applications may be unable to interact with SVA-protected private clouds.

Hybrid cloud support

In the Syncplicity architecture, the software as a service (SaaS) part is called the regional orchestration layer (ROL). This layer manages users, companies, policies, files, folders and other metadata. These are decoupled from the storage that keeps file content. Moreover, storage is plug-gable via the Syncplicity storage connector service. Variations of this service can work with multiple instances of physical storage. ROL doesn't interact with physical storage. It only interacts with the standard simple interface of the storage connector service. This allows attaching multiple instances of storage to a company account.

Syncplicity might host some instances of storage in the Syncplicity public cloud. Customers also might have private clouds where they host storage in their data centers using technology of their choice. For example, you can attach European Union (EU) public storage to a company hosted in the United States (US) ROL, and vice versa. There is no limitation about where a storage connector service runs. An ROL only must provide the necessary storage API.

This architecture requires third-party applications to dynamically discover which storage to use when uploading and downloading files in every user root folder (syncpoint). Moreover, each storage connector service may expose several public URLs where it can be reached. This is done for load balancing and high availability of storage connector services. Application developers can use any strategy to choose which URL to access, but must be able to switch when the preferred URL is unavailable.

While storage connector services are not proxied by the API gateway, they still accept an OAuth 2 access token issued by API gateway, as they contact the API gateway to validate the token. Storage connector services also can use the access token to contact the ROL via the API gateway to retrieve and save their data. Developers should keep this in mind because calling storage connector services can indirectly contribute to the API call quota assigned to the application key.

Storage vault authentication

Storage vault authentication is an additional, optional layer of security in storage connector services. When enabled, storage connector services require an SVA cookie or token to be passed to them along with the OAuth 2 access token issued by Syncplicity API gateway. SVA tokens and cookies are two types of the same user claim that serves as a second part of the key required to access file content via a storage connector service. Keeping the second part of the key separate from the access token enables Syncplicity customers to protect access to their data. File content only becomes accessible after a user authenticates directly on the storage connector service on their client device via a browser. In response, the browser or native application receives an SVA token or cookie, which enables access to storage.

Application developers should understand SVA concepts and determine whether to support it, as there are the following implications:

  • An SVA token or cookie should never leave premises of the user client device. An SVA cookie should stay in the storage connector service domain in a browser and should only be sent there with API calls, which browsers do automatically. An SVA token can be useful to native desktop or mobile applications and might serve the same purpose, but these applications should keep it secure and only send in the storage connector service API calls.
  • Applications that don't implement local storage on the user's client device cannot work with SVA. For example, browser cache for SVA cookie or Windows credential store for SVA token. The only exception are server-side applications running in a trusted customer environment. But such applications are usually implemented by the customers themselves and they only target Syncplicity users of this specific customer.

Multiple data centers

As its global service solution evolves, Syncplicity now supports multiple data centers for storing and managing company and user data that can reside in isolation from other data centers. This addresses privacy and security concerns by storing and processing data and requests within the geographical region. Syncplicity already supports the United States (US) and European Union (EU) regions to fulfill EU safe harbor requirements. The number of data centers is not fixed, and developers should ensure their applications can work with any data center a Syncplicity user belongs to.

Orchestration layers

Orchestration layers are different types of data centers responsible for managing users and their data. There are two types:

  • Global orchestration layer (GOL)
  • Regional orchestration layer (ROL)

Syncplicity architecture supports only one GOL and multiple ROLs. A GOL helps all ROLs cooperate and enables applications to discover the ROL a Syncplicity user belongs to.

Global orchestration layer

The GOL helps the API consumer get information about ROLs and determine which ROL is used as the storage for a user. There is one primary read-only GET request, which allows the API consumer to determine a user's home ROL. The GOL is a public service which doesn't require authorization. The GOL informs the developer of a user's home ROL, where personally identifiable information (PII) is stored, and the host name of the API gateway for each ROL. All API calls have the same endpoint and parameters between each of the ROLs, but the host name of the API gateway that handles that specific ROL is the only difference to the API call URL construction when compared to non-ROL-aware API calls.

Regional orchestration layer

During account creation, a company must select an ROL as the primary data center. Once the company account has been created in Syncplicity, the home region cannot be changed. As only the company home ROL provides access to PII for each company employee, API calls should be directed to the home ROL for looking up PII. Errors return when the API is used in an incorrect ROL for a user.

Host names of the API gateway associated with the ROLs are provided in the table.

API gateway host ROL ROL ID Comments
api.syncplicity.com US 1

ROL for US regional companies that have chosen the US region as the data center during Syncplicity account/company creation. It is also the ROL to use for all existing applications that are not ROL aware.




ROL for EU regional companies that have chosen the EU region as the data center during Syncplicity account/company creation.

Services that return user information, such as syncpoint participants API, return a list of users and the ID of the ROL where they reside. This is needed to look up personal information of a user if the ROL where the user resides is not the home ROL for the Syncplicity user logged into a third-party application.

When an application should be ROL and GOL aware

No changes are needed for existing customer applications implemented against the Syncplicity API gateway in the US data center. All new third-party applications should be GOL and ROL aware by default.

An application should be GOL and ROL aware when the developer knows there are home and remote ROL participants in a single syncpoint where both the US and EU ROL users share the same syncpoint and the users names and emails of the remote users are needed. The application should start calling the GOL to determine users' home ROL, and it should dynamically merge the syncpoints lists shared with specific user from their non-home ROLs. The same applies to retrieving participant information for shared folders (syncpoints) on non-home ROLs. See this topic for more details.

If a company is physically located in a region, it does not mean it resides in that region's ROL. There are many EU customers based in the US ROL. An application should always dynamically determine the ROL a user belongs to.

When an application does not need to be ROL and GOL aware

If you are a Syncplicity customer and implement an application that does not need to be ROL and GOL aware, the only thing you need to know is the host name to invoke for the APIs of your home ROL. If the application was implemented before the multi-data center support was introduced, no changes are needed. Continue invoking the APIs using api.syncplicity.com. If you are a new developer creating a new application, refer to the table to know which is your company’s home ROL.

API gateway host ROL ROL ID
api.syncplicity.com US 1
api.eu.syncplicity.com EU 2