> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicyfalcon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your API requests

## HMAC-SHA256 Authentication

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

## Getting Your Credentials

<Steps>
  <Step title="Navigate to Settings">
    Log in to your UnicyFalcon dashboard and go to **Settings** > **Applications** > **API Keys**
  </Step>

  <Step title="Create New API Key">
    Click on **Create New API Key** button
  </Step>

  <Step title="Save Your Credentials">
    Copy your **API Key** and **HMAC Secret** - the secret is only shown once!
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## Required Headers

Each request must include three authentication headers:

```http theme={null}
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

<CodeGroup>
  ```php PHP theme={null}
  $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,
  ];
  ```

  ```python Python theme={null}
  import time
  import hmac
  import hashlib
  import base64

  method = 'GET'
  uri = '/api/v1/customers'
  body = ''
  timestamp = str(int(time.time()))

  payload = f'{method}|{uri}|{body}|{timestamp}'
  signature = base64.b64encode(
      hmac.new(
          hmac_secret.encode(),
          payload.encode(),
          hashlib.sha256
      ).digest()
  ).decode()

  headers = {
      'X-API-Key': api_key,
      'X-Timestamp': timestamp,
      'X-Signature': signature
  }
  ```

  ```javascript JavaScript theme={null}
  const crypto = require('crypto');

  const method = 'GET';
  const uri = '/api/v1/customers';
  const body = '';
  const timestamp = Math.floor(Date.now() / 1000).toString();

  const payload = `${method}|${uri}|${body}|${timestamp}`;
  const signature = crypto
    .createHmac('sha256', hmacSecret)
    .update(payload)
    .digest('base64');

  const headers = {
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature
  };
  ```
</CodeGroup>

## Timestamp Validation

To prevent replay attacks, the timestamp must not exceed **5 minutes** difference from the server time.

<Info>
  If your timestamp is outside the allowed window, you'll receive a `401 Unauthorized` error with the message: "Request timestamp expired"
</Info>

## 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

<AccordionGroup>
  <Accordion title="401 - Invalid or Missing API Credentials">
    * Check that your API Key is correct
    * Verify your HMAC Secret is accurate
    * Ensure all three headers are present
  </Accordion>

  <Accordion title="401 - Request Timestamp Expired">
    * Your timestamp is more than 5 minutes old
    * Sync your server time with NTP
    * Regenerate timestamp for each request
  </Accordion>

  <Accordion title="401 - Invalid Signature">
    * 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
  </Accordion>

  <Accordion title="403 - Plan Insufficient">
    * Your organization doesn't have API access
    * Upgrade to API plan or higher
    * Contact sales for enterprise options
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Make your first API call
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>
</CardGroup>