Authentication

SmoothIntegration API uses HMAC for authentication. Hash-based message authentication code (or HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. This means that to authenticate against the SmoothIntegration API, you will need both your SmoothIntegration Client ID and SmoothIntegration Client Secret. You can find these on the SmoothIntegration Dashboard Authentication page.

If you're using either Python or JS/TS, we highly recommend you use one of the available SDKS, as they handle the whole authentication mechanism for you. If you do not want to use these SDKs, you can keep on reading to learn how to implement the auth yourself.

Authenticating

The API requires 3 headers to be present to authenticate an incoming request,

Header Description Example
X-Organisation This is your SmoothIntegration ClientID1d1f962c-f9d9-4318-87b2-89c62b737a1d
X-Timestamp An ISO8601 UTC timestamp when the request was made in millisecond precision in format of 'YYYY-MM-DDTHH:mm:ss.sssZ'2024-07-23T16:44:21.220Z
X-Signature The request hash generated using your SmoothIntegration Client Secret in the format of a 64 character lowercase hex string0e7f1090...fdd25c46

Generating the HMAC

The HMAC is created by generating a SHA256 hash using the combination of the request, the time of the request, and your client secret together. The API will then use the same method to generate the hash as well, and if they match, the server knows the request was not tampered with, the sender had the client secret, and that the request was made at a specific time to prevent replay attacks.

So let's actually implement this ourselves,

  1. Generate a Timestamp using the YYYY-MM-DDTHH:mm:ss.sssZ format
  2. Create a new string, containing the following items concatenated, without any separator between them
    1. Your SmoothIntegration Client ID
    2. The HTTP Method in capital letters
    3. The URI, this includes any query parameters
    4. The timestamp generated in the first step. Ensure this is the exact same timestamp as you send in the X-Timestamp header.
    5. The Request payload. Ensure you use the actual buffer of the body you send, this is because JSON objects do not guarantee order, meaning they can serialize differently on different calls.
    Putting it all together, your HMAC payload should look something like this: 
    1d1f962c-f9d9-4318-87b2-89c62b737a1cPOSThttps://api.smooth-integration.com/v1/companies2024-07-23T16:44:21.220Z{"name": "Test Company"}
  3. Now pass this payload to the SHA256 algorithm, using your SmoothIntegration Client Secret
  4. Hex encode the result of the hash. This is the value you need to pass as the X-Signature header. It should look something like this 
    0e7f1090cb9ce05b70ca1bba84cbf1328db8074abe6ff2ef44b4aaccfed25c46