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:
2. In the top-right corner of Postman, click on the environment dropdown

Select SafeSky UAV API - Sandbox (or create a new environment)

Configure EnvironmentCollection Variables:

• Click on the eyeSafeSky iconUAV API (👁️)collection nextname in the sidebar

Go to the environmentVariables dropdown,tab then click Edit

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

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

---