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 ClientID | 1d1f962c-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 string | 0e7f1090...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,
- Generate a Timestamp using the YYYY-MM-DDTHH:mm:ss.sssZ format
- Create a new string, containing the following items concatenated, without any separator between them
- Your SmoothIntegration Client ID
- The HTTP Method in capital letters
- The URI, this includes any query parameters
- The timestamp generated in the first step. Ensure this is the exact same timestamp as you send in the X-Timestamp header.
- 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.
- Now pass this payload to the SHA256 algorithm, using your SmoothIntegration Client Secret
- 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
1d1f962c-f9d9-4318-87b2-89c62b737a1cPOSThttps://api.smooth-integration.com/v1/companies2024-07-23T16:44:21.220Z{"name": "Test Company"}