Testing with Postman

Accessing the Postman Workspace

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

1. Access the Workspace:

   • Visit the SafeSky UAV API Postman Workspace
   • Click Fork Collection to add it to your own Postman workspace

2. What's Included:

   • Pre-configured API requests withfor HMAC-SHA256Live authenticationUAV and Advisory UAV operations
   • Automatic HMAC-SHA256 signature generation using a collection-level pre-request scriptsscript
   • Sample request bodies andwith querydynamic parameters{{timestamp}} variables
   • EnvironmentA variablescollection variable for easy API key configuration

Setting Up Your EnvironmentAPI Key

After forking the collection, configure your environmentAPI variables:key:

1. SelectOpen the Environment:

   • In the top-right corner of Postman, click on the environment dropdown
   • Select SafeSky UAV API - Sandbox (or create a new environment)

2. Configure EnvironmentCollection Variables:

   • Click on the eyeSafeSky iconUAV API (👁️)collection nextname in the sidebar
   • Go to the environmentVariables dropdown,tab
   then
   click Edit

3. Set theYour followingAPI variables:

Key:

Variable	Initial Value	Current Value
server	https://sandbox-public-api.safesky.app	https://sandbox-public-api.safesky.app
ss-api-key	(leave empty)	<your_api_key>

• Important: Set ss-api-key as a secret type variable to keepEnter your API key securein the Current Value column
• TheImportant: Keep the Initial Value will be empty whenso your key is not shared if you shareexport or publish the collection, while Current Value contains your personal API keycollection
• Click Save

4. Verify Environment Selection:

   • Ensure the correct environment is selected in the top-right corner of Postman
   • The environment name should be visible (e.g., "SafeSky UAV API - Sandbox")

Understanding the Authentication

The collection includes a collection-level pre-request script that automatically: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 HMAC-SHA256 signature for each request
• Sets 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
  • Handles
  timestamp generation for request bodies
• Resolves environmentthe variables{{timestamp}} variable in request bodies to the canonicalcurrent requestepoch milliseconds

You don't need to manually configure authentication -— just ensure your ss-api-key environmentcollection 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 theyour environmentAPI key is configured:

1. Select a Request: Choose any request from the collection (e.g., POST multiple UAV lightand -Retrieve return trafficTraffic)
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 environmentcollection 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 correctrequest environment is selected in the top-right corner
• Check that server variableURL points to https://sandbox-public-uav-api.safesky.app
• ReviewCheck that the PostmanContent-Type: consoleapplication/json forheader detailedis errorpresent messageson POST requests
• If you see API_KEY not found, make sure you saved the collection variables after entering your key

---