Getting started with Syncplicity REST APIs: Part 1

Getting started with the Syncplicity REST APIs is simple. I created this “cheat sheet” so that you can get started quickly. You can begin by logging in to the Syncplicity Developer Portal using your Syncplicity Enterprise Account email address. (Click here for the US-based portal or for the EU-based portal.)

Syncplicity REST APIs

You’ll need to have an “Owner” or “Global Admin” role in Syncplicity in order to log in to the Developer Portal.

The Developer Portal will prompt you to create a password for your sandbox account. Once you’re logged in, you’ll have access to the REST API documentation and examples.

The sandbox account is a fully functional Syncplicity Enterprise Account, allowing you to manage users, set Policies and access all the features and administration options of Syncplicity. The owner of this account will be named using your email address but with a “-apidev” added before the at sign (@).

Note for EU users

This document uses US-based information in the examples and contents namely:

• The Developer Portal.
• The base Fully Qualified Domain Name (FQDN) for API calls.

For EU-based users or those users whose accounts or information exist in the Syncplicity European Privacy Region, please replace the above references with the following instead:

• The Developer Portal—replace syncplicity.com (US) with developer.eu.syncplicity.com (EU).
• The base Fully Qualified Domain Name (FQDN) for API calls–replace syncplicity.com (US) with api.eu.syncplicity.com (EU).

Getting your OAuth tokens

To use the APIs, you need to be authenticated with the correct OAuth tokens for your REST API requests.

First, get the base64 encoded OAuth basic token for your App at:

• The Developer Portal, log in, go to the “Applications” tab, select the application, get the “Client ID,” select the “Actions” link, select “View Secret” and get the “”
  • The Client ID looks something like this: 8dVbWYAA0ptx3bD1Syr77JEERI9XwlqY
  • The Secret looks something like this: P9J6ocLOsWCp2X4c
  • If you don’t have them here, create a new App and they’ll be generated for you.
• To use the Client ID and Secret, you need to base64 encode them together.  There are a couple of ways to do this:
  • Go Base64 Encode Org and paste in “<Client ID>:<Secret>”
  • From a Linux Shell, type in:
    • echo -n “<Client ID>:<Secret>” | base64
  • Either way, save this base64 encoded string somewhere safe!
    • The base64 encoded string will look something like this:  OGRWYldZQUEwcHR4M2JEMVN5cjc3SkVFUkk5WHdscVk6UDlKNm9jTE9zV0NwMlg0Yw==
  • NOTE: don’t forget to include the colon (:) between the Key and Secret when performing the above.

Second, get the Syncplicity Application Token for your account:

• Login to your Syncplicity Admin Account, go to your Account tab and find the “Application Token” under your Profile info.
  • If it’s not there, click the “Create” link to create one.
  • Save this token string somewhere safe!

Now you’ve got the two parts you need to use the APIs. To get logged in with OAuth and retrieve your “Bearer token,” perform the following API request:

• URI:
  • https://api.syncplicity.com/oauth/token
• Action:
  • POST
• Headers:
  • ‘Authorization: Basic <base64 string from above>’
  • ‘Sync-App-Token: <Application Token from above>’
• Data:
  • ‘grant_type=client_credentials’

You’ll receive back a bunch of stuff, including the Access Token (also known as a Bearer Token) and Company ID, which you’ll need for your later API calls.

cURL

If you’re a cURL person, the above translates to:

curl -sS -X POST https://api.syncplicity.com/oauth/token -H ‘Authorization: Basic <base64string>’ -H ‘Sync-App-Token: <TokenString>’ -d ‘grant_type=client_credentials’

What you’ll get back is something like this:

{
“issued_at”:”1457653432956”,
“scope”:”readwrite read”,
“user_company_id”:”8c1212c9-1e54-4ce1-b9fd-6f826f2582c3”,
“expires_in”:”5099”,
“user_email”:””,
“organization_id”:”0”,
“token_type”:”BearerToken”,
“client_id”:”WdVRG3ak9CS717BTgZiLZMxYAFTW2sfW”,
“access_token”:”OJnEotf5AhWpM3qsumDG3O8YpBIW”,
“organization_name”:”syncplicity”,
“application_id”:”58497e23-b3cb-4f17-a6e7-e25cca808214”
}

Now you’ve got the Company ID and, more importantly, the Access Token (in green), which is what you’ll need for all your API calls.

Postman

For Postman, enter the above components (URI, Action, Headers, data) into the Postman UI fields:

• Enter request URL = URI from above.
• Select POST for the request type.
• Under the Headers tab, enter the Key and Value pairs = Headers from above.
• Under the Body tab, select Raw = Data from above, without the single quotes.

Next step, go play in the Developer Portal! Using the above, you can now invoke all the other Syncplicity APIs and perform many Syncplicity actions and capabilities.