Skip to main content

Authentication

Getting Started

You should have received an API key from SafeSky. This single key consists of two components:

  • API Key ID: Your public identifier
  • API Secret: Your private secret key used for signing requests

Keep your API secret secure and never expose it in client-side code or public repositories.

⚠️ Important Notice: The legacy X-API-Key header authentication method is deprecated and will be removed in an upcoming release. All integrations must migrate to HMAC authentication as described below. Please update your implementation as soon as possible to avoid service interruption.

HMAC Authentication

SafeSky API uses HMAC (Hash-based Message Authentication Code) for request authentication. This scheme provides several key benefits:

  • Security: Credentials are never sent over the network; only a cryptographic signature is transmitted
  • Integrity: Ensures requests haven't been tampered with during transit
  • Replay Protection: Timestamps prevent replay attacks
  • Stateless: No session management required on the server side

HMAC uses the SHA-256 hashing algorithm to create a unique signature for each request based on the request content and your API secret.

SDKs and Libraries

To simplify integration, SafeSky provides official SDKs for multiple platforms:

These SDKs handle HMAC signature generation, request signing, and error handling automatically. We recommend using an SDK whenever possible to reduce implementation complexity and potential security issues.

Manual HMAC Implementation

If an SDK is not available for your platform, you can implement HMAC authentication manually.

Request Signature Components

Each authenticated request must include the following headers:

X-SafeSky-Key-Id: <your-api-key-id>
X-SafeSky-Timestamp: <unix-timestamp-in-seconds>
X-SafeSky-Signature: <hmac-signature>

Signature Generation Process

  1. Create the Signature Base String

    Concatenate the following components with newline characters (\n):

    <HTTP-METHOD>\n
<REQUEST-PATH>\n
<TIMESTAMP>\n
<REQUEST-BODY>
    • HTTP-METHOD: Uppercase HTTP method (GET, POST, PUT, DELETE, etc.)
    • REQUEST-PATH: The path and query string (e.g., /api/v1/flights?status=active)
    • TIMESTAMP: Unix timestamp in seconds (must match the X-SafeSky-Timestamp header)
    • REQUEST-BODY: Raw request body for POST/PUT requests, or empty string for GET/DELETE

  2. Generate HMAC Signature

    Compute the HMAC-SHA256 hash of the signature base string using your API secret:

    signature = HMAC-SHA256(api_secret, signature_base_string)

  3. Encode the Signature

    Convert the signature to hexadecimal format (lowercase).

Example Implementation

cURL

#!/bin/bash

API_KEY_ID="your_api_key_id"
API_SECRET="your_api_secret"
METHOD="GET"
PATH="/api/v1/flights"
TIMESTAMP=$(date +%s)
BODY=""

# Create signature base string
SIGNATURE_BASE="${METHOD}\n${PATH}\n${TIMESTAMP}\n${BODY}"

# Generate HMAC signature
SIGNATURE=$(echo -n -e "${SIGNATURE_BASE}" | openssl dgst -sha256 -hmac "${API_SECRET}" | cut -d' ' -f2)

# Make request
curl -X GET "https://api.safesky.app${PATH}" \
  -H "X-SafeSky-Key-Id: ${API_KEY_ID}" \
  -H "X-SafeSky-Timestamp: ${TIMESTAMP}" \
  -H "X-SafeSky-Signature: ${SIGNATURE}"

Important Considerations

  • Clock Synchronization: Ensure your system clock is synchronized with NTP. The API will reject requests with timestamps more than 5 minutes old or in the future.
  • Character Encoding: Always use UTF-8 encoding for the signature base string.
  • Body Serialization: For POST/PUT requests, use the exact body bytes that will be sent (typically JSON). Don't modify or pretty-print the JSON after signing.
  • Query Parameters: Include query parameters in the path component (e.g., /api/v1/flights?status=active).
  • Signature Case: The signature must be lowercase hexadecimal.

Error Responses

Authentication failures will return HTTP 401 with one of the following error codes:

  • invalid_signature: The signature doesn't match the expected value
  • invalid_timestamp: The timestamp is too old or too far in the future
  • invalid_key: The API key ID is unknown or inactive
  • missing_headers: Required authentication headers are missing

Testing Your Implementation

To verify your implementation:

  1. Test with a simple GET request to /api/v1
  2. Compare your signature generation with the SDK implementation
  3. Enable debug logging to inspect the signature base string
  4. Verify timestamp synchronization with date +%s vs server time

For additional support, contact SafeSky technical support or refer to the full API documentation.

Back to top