Authentication

Authentication

The following information provides a detailed overview of the Sovos Simple Connect API requests and responses, including explanations of each call with relevant parameters and endpoints.

Users of the Simple Connect API on both environments are required to provide an authentication string in the Authorization header of the request. Requests require an authentication string based on the standard Basic schema, this string is obtained by generating a Base64 digest with concatenation of the API key and the secret key separated by a colon character (:). The resulting value will be passed as “Basic ” in the Authorization header of the request to authenticate the given request within the Simple Connect API.

Basic schema algorithm:

Basic <Base64(<api_key>:<secret_key>)>

For code samples for generating the values required for authentication see Basic Authentication Code Samples.

Optional HMAC Authentication for Production

The Production environment also supports the authentication via a HMAC hash. This is accomplished by generating a digest using the HMAC-SHA256 and Base64 functions with the access key, the secret key, and the current timestamp as parameters. In that case also the URL of the target endpoint for the request should have the “/api/basic-auth” prefix instead of “/api/pre-auth”.

HMAC schema algorithm:

<access_key>:<Base64(HMAC256(<secret_key>, <timestamp><access_key>))>

In the algorithm above you can see that a Base64 digest is concatenated with the access key and a colon as a separator. That digest is the result of a Base64 function applied to a HMAC-256 hash generated with the concatenation of the timestamp and the access key as the message and the secret key as the secret passphrase. Also the same timestamp that will be included in the generation of the authorization header needs to be included in a x-request-date header. The timestamp for both the x-request-date header and the authentication algorithm is the current time in UTC  in ISO 8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ).

Headers

The following headers must be included with each request:

  • x-request-date: (Required for the HMAC authentication schema) Current request date in ISO 8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ).
  • Authorization: (Required) Standard Basic-based string (optionally could be the HMAC-based schema for Production environment).