Authentication

You'll need to authenticate your requests to access any of the endpoints in the Sufy API. In this guide, we'll look at how authentication works.

🔑 Api token

api tokens can be used to access our services via api. All of sufy's services can be accessed using api tokens unless otherwise specified.

The token is generated using the HMAC Sha1 algorithm, which is a widely used algorithm for generating api tokens.

Signing a URL involves the following steps:

  1. Obtain the original URL The input URL must start with "https://" or "http://" and must not contain the "expires" and "token" query parameters.
// example
var apiUrl = "https://api.sufy.com/example"
  1. Add the expiration time parameter If the URL already contains query parameters, use "&" as the separator to add the new parameter; otherwise, use "?" as the separator. Add the "expires" query parameter, with the value being the Unix timestamp of the given expiration time.
sep := "?"
if strings.Contains(apiUrl, "?") {
  sep = "&"
}
apiUrl += sep
apiUrl += fmt.Sprintf("expires=%d", expiration.Unix())
  1. Generate the signature Use the HMAC-SHA1 algorithm to sign the constructed URL with the given 🔑secretKey. Encode the signature result using Base64 URL encoding. For information on how to get the secretKey, see here.
mac := hmac.New(sha1.New, []byte(secretKey))
mac.Write([]byte(apiUrl))
signature := base64.URLEncoding.EncodeToString(mac.Sum(nil))
  1. Add the signature information Append the "token" query parameter to the URL, in the format "accessKey:signature".
apiUrl += fmt.Sprintf("&token=%s:%s", accessKey, signature)
  1. Return the final signed URL Return the complete URL after the signing process, for the user to utilize.

HMAC-SHA1

HMAC-SHA1 is a type of message authentication code algorithm based on hash functions. It combines a secret key and the message input, and produces a fixed-length message digest as the authentication code using the SHA-1 hash function.

The key features of HMAC SHA-1 include:

  • Security: The HMAC algorithm provides message authentication by using a secret key, which can defend against various attacks such as man-in-the-middle attacks and replay attacks. The SHA-1 algorithm itself is also widely used in security applications.
  • Efficiency: The HMAC algorithm is computationally efficient, making it suitable for scenarios that require frequent message authentication.
  • Flexibility: The HMAC algorithm can be used in combination with different hash functions such as SHA-256, MD5, etc., to meet diverse security requirements.
  • Standardization: The HMAC algorithm is standardized by RFC 2104 and has gained widespread adoption and recognition.

HMAC-SHA11 is widely used in the areas of network security, digital signatures, and message authentication. It is a well-established secure algorithm that plays an important role in protecting data integrity and authentication.