User Authentication

Users must be identified (authenticated) before you can determine their access.  This is typically done via a Sign-in process.  SyncAccess offers an API that external applications can use to sign users into the system.  Users provide their credentials (username and password) and those values are checked against the syncAccess database.

The process is similar to application authentication except that credentials must be gathered from the user (i.e., via a log-in form).  

Getting User Credentials

It's your responsibility to gather the users' credentials in a secure fashion.  For example, you might build a dedicated log-in form or page so the user can enter the credentials.  You might also pull the values from a local secure storage repository.  

User Authentication API (aka Login API)

The user authentication API looks similar to the application authentication API.  You'll issue a POST request to a different URL this time.  The URL is specific to the customer instance you are connecting to.  ePublishing support will provide this value for you.  It will typically look like this:  https://{Client-Specific-Domain}/appservices/token.  The domain name for your integration will be different.

As with the Application Authentication API, the body of your POST request must be formatted as x-www-form-urlencoded values and should contain the following parameters

Key Value
grant_type password
username (username from login form/process)
password (password from login form/process)

For example, if the user enters [email protected] and AbCd123xyz! for her credentials, then you'd construct a POST request like this.

curl --location --request POST 'https://subscribe.acmenews.com/appservices/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: applicaton/json' \
--header 'Origin: https://foobar.com' \
--data-urlencode 'grant_type=password' \
--data-urlencode '[email protected]' \
--data-urlencode 'password=AbCd123xyz!'
Click to copy

If the user's credentials are valid, the API would return a JSON response like shown below.

{
    "access_token": "UkOidEVo610dKNwyStOTBk5K5QfySRZddReVjXRc1Vqlm...NHH3OspfFgw",
    "token_type": "bearer",
    "expires_in": 1800,
    "refresh_token": "3e277ffa6349407a9a29d2fc3631da2558e4a544504e46269449c6cf640e3bc5",
    "username": "[email protected]"
}
Click to copy

The important properties are the access_token and the expires_in properties.

  • The access_token holds the user's authentication token.  This value should be saved as it's used in subsequent API calls.  
  • The expires_in property shows the number of seconds until the user token expires.  In the above example, the token is valid for 30 minutes.  Note that this is a configurable property and different for every customer.  Subsequent requests made with an expired token will result in a 401-Unauthorized response.

Requests with invalid credentials (i.e., incorrect password), will result in a 400-Bad Request response along with some brief error information like that shown below.

{
    "error": "invalid_grant",
    "error_description": "The user name or password is incorrect."
}
Click to copy