API Security
API Users
The data extract APIs can only be accessed by an API User account. Any current administrator can create these API users via the administrative console's Settings --> Users menu.
Click Add a New User
Give the new user an appropriate Username and Password. The other fields like email, first name, and last name can be anything you want. Only the username and password are required for accessing the API methods.
Make sure the new user is given the role of Api User (place a check next to that role). This is the only role that the user needs in order to access the APIs. The other roles shouldn't be selected unless you have specific need to allow the new user to access other functionality in the Admin console.
syncAccess supports two authentication methods for accessing these secured APIs: Bearer token Authentication and Basic Authentication.
Accessing the APIs with Bearer Token Authentication
This method is part of the oAuth 2.0 specification's Resource Owner Password Credentials Grant mechanism (RFC-6749) and is the preferred mechanism for accessing the APIs.
Getting an Access Token
To use this authentication mechanism, the API user must request an access token that can be used in the API request. This is done via the /token URL endpoint. A POST request with the user credentials is sent to this endpoint and, if the credentials are valid, an access token is returned in the response.
The body of the request must contain the following fields:
| grant_type | Always password |
| username | The username associated with the account created in the Admin console |
| password | The password associated with the account created in the Admin console |
The request can use a content type of x-www-form-urlencoded or applicaton/json. The credentials are posted to:
https://syncaccess-co-prop.stage.syncronex.com/appservices/token (stage)
https://syncaccess-co-prop.syncronex.com/appservices/token (production)
(where co is the company and prop is the property that your site was assigned.)
If the credentials are valid, a JSON response is returned containing the access token. For example:
{
access_token: RTbLmmRQITi-lpeiFPQaYPLtOYUTqBZkrf7mgK4g892WMm5tRukde2tSZHsICf5Lpt_n_66VTuH3Xqhpv35r4Bm_BW8cegjSTB5N40zoPPGS3Qnrg5KzoHpgip97afreIzg8IH8qV-SSyks5EgG8BiiFHiKeKC3k4Xe98vawkIWWHnUguGd42tS2I35uqJHZfAIoEnp7XxqAyaLvCoKdjjgjdvvTrFnXv2GD6Dds-MqdLA-ipqEo4ZEJFVKhqath9QXgHa3jwMgMj9Cem2X9w7ApRivc7QvEuF-t35LN5bXW-7SwI3XPn9Ev8Hfzl8idwxcQ-JqqWKaixYCwKKen25x_SFI,
token_type: bearer,
expires_in: 1799,
username: apiuser1
}Here's an example call to the token endpoint using curl
.\curl.exe -X POST --header "Accept: application/json" --header "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=apiuser1&password=mypass1" https://syncaccess-hst-sfc.stage.syncronex.com/appservices/token
Using an Access Token to Request API Data
The access token is used in lieu of user credentials in each API request. Include the token in the Http Authorization header like this:
Authorization: bearer RTbLmmRQITi-lpeiFPQaYPLtOYUTqBZkrf7mgK4g892WMm5tRukde2tSHere's an example of a call to the Subscribers Data API (described later) using curl (note, the full access token has been shortened for sake of example)
curl -X GET --header "Accept: application/json" --header "Authorization: bearer bUnUAje3MNbuSuWM7k_...Henqb_oIi3_wwcI2UZwROzc0wSA" https://syncaccess-sync-demo1.stage.syncronex.com/appservices/api/v1/External/Data/NCS/Subscribers
note: the access token is only valid for 30 minutes. If the access token expires, you must receive a new one using the /token endpoint above.
Using Http Basic Authentication to Access API Data
syncAccess also supports Http Basic Authentication for those customers whose environments or tools make the bearer token authentication mechanism too difficult. Basic authentication still requires the use of a specific API User account but might be easier to implement. With basic authentication, the user account credentials must be sent with each request as part of the Authorization header.
Authorization: Basic base64-encoded-credentialsThe credentials are appended with a colon : character and then encoded using Base64 encoding (this is done strictly to ensure that only allowed characters are sent over the wire. This is not a form of encryption and provides no inherent security. All requests to syncAccess APIs are required to be sent over a secure transport layer which does ensure that the credentials are securely encrypted)
Here is another curl example that access the Subscribers Data API endpoint using Basic Authentication:
curl-X GET --header "Accept: application/json" --header "Authorization: Basic cm9iY29tYXBpOnJvYmNvbTg4" https://syncaccess-sync-demo1.stage.syncronex.com/appservices/api/v1/External/Data/NCS/Subscribers