How do I set up HMAC API authentication?

Starting September 25, 2026, all Smoobu API requests must be authenticated using HMAC-SHA256 signatures. This guide explains how you are affected and provides step-by-step instructions to update your integration. 

What is HMAC authentication?

HMAC (Hash-based Message Authentication Code) is a security standard that ensures each API request is authentic and hasn't been tampered with.

Instead of sending just your API key, each request is signed with a secret — similar to how banks verify transactions.

Does this affect me?

• No: You are not affected if you only use official partner integrations connected through the Smoobu Marketplace (e.g., PriceLabs, Chekin). These partners handle the migration automatically on their end.
• Yes:
  • If you use the Smoobu API directly through your own scripts or custom integrations where you control the code, you are Follow the steps below. 
  • If you pasted your Smoobu API key into a third-party tool that you do not control (for example, a pricing tool or channel manager that is not in the Smoobu Marketplace). You cannot migrate this yourself, because the tool's provider has to implement the new signing on their side. See "Using a third-party tool?" below. 

Are you using a third-party tool?

If your API key is used by a third-party tool you do not control, do not delete your key or try to migrate it yourself - that would break the integration. 

Instead, contact our support team and tell us which tool you are using. We will reach out to the provider directly and set them up with the new  signing method. Your existing API key stays the same, and your integration keeps working throughout the migration window while we handle this.

Step-by-Step

1) Open your Smoobu account and navigate to Advanced > API Keys

2) Click Create New, then give your key a descriptive label (e.g., “My Smoobu integration” or “Channel sync script”) so you can easily identify it later. Click Submit.

3) After clicking "Submit," your secret will be displayed once—copy it immediately and store it in a safe place (like a password manager or your application's environment variables).

💡 Tip: If you lose your secret, you can regenerate it on this page. Note that regenerating will immediately invalidate the existing secret, so make sure to update your integration first.

4) Update your integration to sign requests. The full technical guide with code examples is available here: docs.smoobu.com/#hmac-authentication 

Every API request now requires these headers:

5) During the migration window (now through September 25, 2026), Smoobu accepts both signed and unsigned requests. You can deploy your updated integration and verify it works without breaking your existing setup. 

💡Tip: Send a few requests with the new headers and check that you get successful responses. If you see 401 Unauthorized, double-check your timestamp (must be within 5 minutes of server time) and ensure your nonce hasn't been reused

6) Delete your old API key (optional, but recommended). If you have an API key under Legacy API Keys, you can delete it once you've set up your new key. During the migration window both old and new keys work, so you can do this after completing testing.

💡 Tip: Don't delete your old key until your new signed integration is working. Both can coexist during the migration window.

FAQ

Who does these changes apply to?

This applies is if you use the Smoobu API directly, for example with:

• Your own scripts
• Custom integrations
• Third-party tools where you manually entered your API key

If you use a partner integration through the Smoobu Marketplace (such as Pricelabs, Chekin, or similar integrations), no action is required on your part. Your integration partner will handle the upgrade. 

Furthermore, API connections with channels (Airbnb, Booking.com, etc) are also unaffected by this change.

What stays the same?

• Your API key value does not change
• All existing Smoobu API endpoints work exactly as before
• The same data formats and responses apply

What’s new?

• Each request includes a timestamp, a unique nonce, and a signature
• You generate a secret from your Smoobu dashboard to create that signature

I’m getting 401 Unauthorized — what should I check?

Common causes:

• Clock skew — your system time is off by more than 5 minutes. Make sure your server uses NTP.
• Reused nonce — every request must have a unique X-Nonce. Use UUID v4 or random bytes.
• Wrong body hash — for GET/DELETE requests, hash an empty string (not null or undefined).
• Query string order — parameters must be sorted alphabetically when building the canonical string.
• Encoding mismatch — sign the raw JSON body exactly as it is sent (same whitespace and encoding).

My old API key stopped working — what happened?

If you are past the September 25, 2026 cutoff and have not added HMAC signing, unsigned requests return 401 error.

To fix this:

1. Go to Advanced > API Keys
2. Create a new key and generate a secret
3. Update your integration to sign requests

Can I still use my old API key value?

Yes. Your API key value stays the same.

You only need to add these headers alongside your existing X-API-Key:

• X-Timestamp
• X-Nonce
• X-Signature

What happens if I lose my secret?

1. Go to: Advanced > API Keys
2. Find your key and click Regenerate Secret.
3. The old secret stops working immediately, so update your integration right away.

What is the migration timeline?

Full technical guide

For the complete technical reference — including detailed code examples in cURL, PHP, and Node.js — visit the Smoobu API documentation:

https://docs.smoobu.com/#hmac-authentication

This page has everything you need to implement HMAC signing in your integration.