- 2 Minutes to read
- DarkLight
API Authentication
- 2 Minutes to read
- DarkLight
To authenticate with the API, you must be provided with the following information from your Syndigo account representative:
- Username
- Secret (URL Encoded in Request)
The API credentials are located within My Account > API Settings. See screenshots below.
After selecting API Settings, you should see the API credentials:
You must have admin permissions to see the API credentials! Make sure one of your sub-accounts is privileged to see them. If you still can't see them, reach out to your Customer Success Manager or Account Executive.
Syndigo Integration APIs utilize a bearer token authentication scheme. The Secret is valid indefinitely; the tokens generated have expirations. Tokens are valid for 7 days in UAT (sandbox) to ease the process of testing and prototyping, but in production, each token is valid for 60 minutes (tiny variance possible for the potential time-skew and other caching timeouts on the servers validating it).
This makes the token validity duration to be 60 minutes plus or minus a few minutes. You must track the time you created the token and automatically refresh it to use or you can capture 401 responses and re- authenticate and retry.
The authentication token length can vary widely. This token consists of a list of claims and permissions, which then gets hashed and cryptographically signed and encoded. So, as we add permissions and claims to our system, the token gets longer. As this token is an irrevocable key, Syndigo recommends treating it with the same security measures as you would treat a password.
The bearer tokens, if exposed allows anyone to impersonate you until that token expires. Ensure you transmit bearer tokens over HTTPS.
To Retrieve a Bearer Token:
- Call the Auth API by providing the username and secret URL parameters:
Production endpoint - https://api.syndigo.com
UAT endpoint - https://api.uat.syndigo.com
https://api.uat.syndigo.com/api/auth?username=YourApiUsername&secret=YourUrlEncodedSecret
2. Alternatively, you can put your username and secret in the body of a request. In the response you will get an auth token.
- Request a bearer token from the Auth API:
curl -G "https://api.uat.syndigo.com/api/auth" --data-urlencode "username=YOURUSERNAME" --data- urlencode "secret=YOURSECRET" - Extract the “Value” property or the bearer token from the returned JSON object.
- Add the bearer token to the Authorization header in subsequent requests.
- The Auth API includes a “test” endpoint to validate that you are correctly executing requests. The authorization scheme is “EN ”. For example, if the returned bearer token is “ABCDEFG”, the curl command to test auth would be:
curl -H "Authorization: EN ABCDEFG" https://api.uat.syndigo.com/api/auth/test - There's an option to skip appending "EN" if desired. In a response call, you will receive an attribute called "AuthHeader" that includes a token with the authorization scheme.