Skip to main content

​
HMAC-SHA256 Authentication

UnicyFalcon API uses HMAC-SHA256 authentication to ensure the security and integrity of requests.

​
Getting Your Credentials

1

Navigate to Settings

Log in to your UnicyFalcon dashboard and go to Settings > Applications > API Keys
2

Create New API Key

Click on Create New API Key button
3

Save Your Credentials

Copy your API Key and HMAC Secret - the secret is only shown once!
Keep your HMAC Secret secure! It’s only displayed once and cannot be recovered. If lost, you’ll need to generate a new key pair.

​
Required Headers

Each request must include three authentication headers: 
X-API-Key: your_api_key
X-Timestamp: unix_timestamp
X-Signature: hmac_signature_base64

​
Signature Algorithm

The signature is generated using the following algorithm: 
payload = METHOD|URI|BODY|TIMESTAMP
signature = base64_encode(hash_hmac('sha256', payload, hmac_secret, true))

​
Payload Components

  • METHOD: HTTP method in uppercase (GET, POST, PUT, DELETE)
  • URI: Full URI path (e.g., /api/v1/customers)
  • BODY: Request body (empty string for GET requests)
  • TIMESTAMP: Unix timestamp of the request

​
Example Implementation

$method = 'GET';
$uri = '/api/v1/customers';
$body = '';
$timestamp = time();

$payload = $method . '|' . $uri . '|' . $body . '|' . $timestamp;
$signature = base64_encode(hash_hmac('sha256', $payload, $hmacSecret, true));

$headers = [
    'X-API-Key: ' . $apiKey,
    'X-Timestamp: ' . $timestamp,
    'X-Signature: ' . $signature,
];

​
Timestamp Validation

To prevent replay attacks, the timestamp must not exceed 5 minutes difference from the server time.
If your timestamp is outside the allowed window, you’ll receive a 401 Unauthorized error with the message: “Request timestamp expired”

​
Testing Your Authentication

You can test your authentication using our interactive API browser at: 
https://{your-subdomain}.unicyfalcon.com/api/test/api-browser

​
Common Errors

  • Check that your API Key is correct
  • Verify your HMAC Secret is accurate
  • Ensure all three headers are present
  • Your timestamp is more than 5 minutes old
  • Sync your server time with NTP
  • Regenerate timestamp for each request
  • Verify the payload format: METHOD|URI|BODY|TIMESTAMP
  • Ensure URI includes /api/v1/ prefix
  • Check that body is exact JSON string (no formatting)
  • Confirm you’re using HMAC-SHA256 with binary output
  • Your organization doesn’t have API access
  • Upgrade to API plan or higher
  • Contact sales for enterprise options

​
Next Steps

Quick Start

Make your first API call

API Reference

Explore all available endpoints