Skip to main content

Testing with Postman

Accessing the Postman Workspace

To get started with testing the SafeSky UAV API, you can access SafeSky's online Postman workspace with pre-built requests and authentication:

  1. Access the Workspace:

  2. What's Included:

    • Pre-configured API requests for Live UAV and Advisory UAV operations
    • Automatic HMAC-SHA256 signature generation using a collection-level pre-request script
    • Sample request bodies with dynamic {{timestamp}} variables
    • A collection variable for easy API key configuration

Setting Up Your API Key

After forking the collection, configure your API key:

  1. Open Collection Variables:

    • Click on the SafeSky UAV API collection name in the sidebar
    • Go to the Variables tab

  2. Set Your API Key:

    Variable Initial Value Current Value
    ss-api-key (leave empty) <your_api_key>
    • Enter your API key in the Current Value column
    • Important: Keep the Initial Value empty so your key is not shared if you export or publish the collection
    • Click Save

Understanding the Authentication

The collection includes a collection-level pre-request script that automatically runs before every request. It:

  • Derives a KID (Key Identifier) from your API key using SHA-256
  • Derives an HMAC signing key using HKDF-SHA256 (salt: safesky-hmac-salt-v1, info: auth-v1)
  • Generates an ISO 8601 timestamp and a UUID v4 nonce
  • Builds a canonical request (method, path, sorted query string, headers, body hash)
  • Computes the HMAC-SHA256 signature
  • Sets the required authentication headers automatically:
    • Authorization — SS-HMAC Credential={kid}/v1, SignedHeaders=host;x-ss-date;x-ss-nonce, Signature={sig}
    • X-SS-Date — Current ISO 8601 timestamp
    • X-SS-Nonce — Unique UUID v4
    • X-SS-Alg — SS-HMAC-SHA256-V1
  • Resolves the {{timestamp}} variable in request bodies to the current epoch milliseconds

You don't need to manually configure authentication — just ensure your ss-api-key collection variable is set correctly.

Available Requests

All requests target the production endpoint https://uav-api.safesky.app.

Live UAV Operations (/v1/uav)

Request Method Description
GET nearby aircraft by viewport GET Retrieve traffic within a bounding box (viewport parameter)
GET nearby aircraft by radius GET Retrieve traffic within a radius (lat, lng, radius parameters)
Publish UAV POST Publish a single UAV position
Publish UAV and Get Nearby Aircraft POST Publish a UAV position and retrieve nearby traffic (return_nearby_traffic=true)
POST UAV with icao POST Publish a UAV position with an ICAO24 transponder code
POST UAV light POST Publish a minimal UAV position (only required fields)
POST multiple UAV and Retrieve Traffic POST Publish multiple UAV positions in a batch and retrieve nearby traffic

Advisory UAV Operations (/v1/advisory)

Request Method Description
Publishing a Polygon Advisory POST Publish an advisory zone defined by a GeoJSON Polygon
Publishing a Point Advisory with a Radius POST Publish an advisory zone defined by a GeoJSON Point with max_distance
Publishing Multiple Advisories POST Publish multiple advisories (polygon + point) in a single request

Other

Request Method Description
Check API health GET Verify the API gateway is reachable

Start Testing

Once your API key is configured:

  1. Select a Request: Choose any request from the collection (e.g., POST multiple UAV and Retrieve Traffic)
  2. Review the Request: Check the request body and query parameters — {{timestamp}} is resolved automatically
  3. Send the Request: Click Send
  4. View the Response: The API will return nearby aircraft traffic based on your UAV positions

Troubleshooting

If you encounter authentication errors:

  • Verify your ss-api-key is correctly set in the collection Variables tab (check the Current Value column)
  • Open the Postman Console (View → Show Postman Console) to see ✓ Authentication headers set or any error messages
  • Ensure the request URL points to https://uav-api.safesky.app
  • Check that the Content-Type: application/json header is present on POST requests
  • If you see API_KEY not found, make sure you saved the collection variables after entering your key
Back to top