Application Authentication

External applications that need to interact with the system's APIs must authenticate to prove they are a valid application.  ePublishing support can provide you with a client application Id and password that you can use to sign your application in.

Authentication involves making an API call to the system's Identity provider and providing your application's credentials.  To sign in, you'll need:

  • Your Client application Id ("client_id")
  • Your Client application password ("client_secret")
  • The target syncAccess "Tenant" ("scope")

All of these values will be provided by ePublishing support.  If you are missing any one of these, contact support ([email protected]).

Authentication Token API

Call the Client Authorization API to authenticate your application and receive an application token.  You'll make a POST request to https://identity.syncronex.com/oauth/token.

Your request must use the x-www-form-urlencoded content type and should contain the following parameters

Key Value
grant_type client_credentials
scope (your client tenant id)
client_id (your client application id)
client_secret (your client application password)

For example, if your application id is app_acme_news_prod and your application password is ABC1234XYZ and your target tenant is acme_news_prod, then you'd construct a POST request as shown in the following cUrl snippet.

curl --location --request POST 'https://identity.syncronex.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=acme_news_prod' \
  --data-urlencode 'client_id=app_acme_news_prod' \
  --data-urlencode 'client_secret=ABC1234XYZ'
Click to copy

The API will respond with JSON describing the authentication details or an error message if the authentication attempt failed. A successful authentication would return a response similar to the following.

{
    "access_token": "dbjsQpS5gI2RnII6wv...DCMqb3lyBv9Wsy95VUjdEf",
    "token_type": "bearer",
    "expires_in": 1199,
    ".issued": "Thu, 01 Dec 2022 19:59:20 GMT",
    ".expires": "Thu, 01 Dec 2022 20:19:20 GMT"
}
Click to copy

Most of the details in the response can be ignored, but there are two critical items you must attend to.

  1. The access_token holds your application token. You'll need to save that for user later.
  2. The expires_in property shows the number of seconds until your token expires. This is typically about 20 minutes.  Subsequent requests made with an expired token will result in 401-Unauthorized responses.  You'll need to re-authenticate your application to refresh your token.
    (the .expires property contains the same information as an explicit date and time on which the token would expire)

An unsuccessful authentication will return a response similar to the one shown below.

{
    "error": "invalid_grant",
    "error_description": "Client authentication failed"
}
Click to copy

This would typically be accompanied by a 400-Bad Request HTTP response code.

The application authentication API is not client-specific.  It will always be https://identity.syncronex.com/oauth/token regardless of the specific client you are integrating with.