Enabling a 30-Day Free Trial

This guide explains how to embed a zero-configuration 30-day SafeSky trial directly inside your own product (a drone platform, fleet manager, ground control station, or mission-planning tool) so that every one of your customers gets full SafeSky air-traffic awareness the moment they flip a single toggle, with no SafeSky account, no API key, and no credit card required up front.

It is written for two audiences:

• Product & business owners, start with the Why section to understand what the trial unlocks for your platform and your customers.
• Developers, jump to the Integration sections for the exact headers, authentication, and trial-expiry handling you need to ship.

Reference platform: https://www.safesky-enterprise.com

---

Why Offer a Built-In SafeSky Trial?

Air-traffic awareness is one of the strongest safety and differentiation features you can add to a drone product, but historically every operator had to register with SafeSky, obtain an API key, and manage a subscription before they could see a single aircraft. That friction kills adoption.

The built-in trial removes it entirely. With one toggle, your customers get 30 days of full send-and-receive traffic, and you get a frictionless way to demonstrate value before anyone is asked to pay.

What Your Customers Get

• Instant activation, no SafeSky registration, no API key, no forms.
• Full feature access, both share (broadcast their drone positions) and receive (see surrounding manned and unmanned traffic) for the entire 30-day period.
• Unlimited usage during the trial, the trial is time-boxed, not capped by a usage quota. For 30 days there is no minute budget, no flight-hour budget, and no throttling.
• A seamless upgrade path, when the trial ends, customers simply paste a SafeSky API key into your configuration screen to keep receiving traffic.

What Your Platform Gets

Benefit	Description
Higher adoption	A one-click safety upgrade with zero onboarding friction.
Proven value before purchase	30 days of real-world experience drives conversions far better than a sales demo.
A safety story	Every customer broadcasting positions makes the shared airspace safer, including for manned aviation.
No burden on you	SafeSky takes care of trial provisioning, metering, and conversion.

How It Works at a Glance

┌──────────────────────────────────────────────────────────────┐
│  Your Product                                                │
│                                                              │
│   [ ON ]  Enable SafeSky Network                             │
│           Share positions + receive traffic.                 │
│           Includes a 30-day free trial.                      │
│                                                              │
│   SafeSky API Key (optional) ........... [            ]      │
│           Add a key to keep receiving traffic after trial.   │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
      Blank key field  ──►  Use embedded SafeSky integration key
                            + per-customer trial (30 days)
      Filled key field ──►  Use the customer's own SafeSky key
                            + their own subscription

The toggle activates the SafeSky traffic feature. The optional API key field decides which credentials are used:

• Field blank → your product authenticates with the integration key SafeSky issued you (a shared secret embedded in your application), and each customer runs on an automatic per-customer 30-day trial.
• Field filled → your product authenticates with the customer's own SafeSky API key, and traffic reception is governed by their subscription.

---

1. Before You Begin

To enable trials inside your product you need one thing from SafeSky: an integration key.

• Contact SafeSky to set up a partner contract and receive your integration key, a shared secret you embed in your application. It authenticates every trial request until a customer enters their own key.
• The integration key uses the same HMAC authentication scheme as a standard SafeSky API key (see Authentication). There is nothing new to learn about signing requests.
• The integration key is never billed itself. It only unlocks per-customer trials when paired with an organization identifier (below).

Get your integration key: https://www.safesky-enterprise.com

---

2. The Organization Identifier (X-SS-Org-Id)

Each of your customers (a tenant, account, workspace, or organization on your side) must be identified to SafeSky by an organization token, sent as the X-SS-Org-Id HTTP header on every request.

This token is what gives each customer their own independent 30-day trial clock.

GET /v1/uav?viewport=48.8566,2.3522,48.8766,2.3922
Authorization: SS-HMAC Credential={kid}/v1, SignedHeaders=host;x-ss-date;x-ss-nonce, Signature={sig}
X-SS-Org-Id: 9f1c2e7a4b8d...

Token Requirements

The token does not need to be, and should not be, your customer's real organization id. It can be any value you derive from the organization, as long as it satisfies three properties:

Unique
Distinct customers map to distinct token values. Two customers sharing a token would share a single trial.

Stable / immutable
The same customer always produces the same token, forever. A changed token starts a brand-new trial and resets the clock.

Opaque
Carries no personal data; meaningless to SafeSky. Protects your customers' privacy. A hash of the real id is encouraged.

Recommended approach: generate a one-way hash (e.g. SHA-256) of your internal organization id, or a stable opaque UUID stored once per organization. Persist it and never change it.

Critical: The trial is keyed entirely on this value. Emitting a different token for the same customer grants them a fresh trial; reusing one customer's token for another makes them share a single trial. Generate it once, store it, and send the same value every time.

---

3. Authentication Switching

Your configuration screen exposes a toggle and an optional API key field. Choose credentials based on whether the field is filled:

Scenario	Authentication	X-SS-Org-Id	Share positions	Receive traffic
API key field blank	Embedded integration key	Required	Unlimited	30-day trial, then empty
API key field filled	Customer's own API key	Optional (ignored for auth)	Unlimited	Subscription based

Important rules:

• An integration key without X-SS-Org-Id is rejected with HTTP 400 Bad Request, the key may never be used anonymously, because there would be no customer to attribute the trial to.
• When the customer enters their own key, send their key and (optionally) keep sending X-SS-Org-Id for your own analytics, SafeSky ignores it for account resolution in that case.

---

4. Using the API During a Trial

Once the integration key + X-SS-Org-Id are in place, the SafeSky UAV API behaves exactly like a normal paid integration. There is no special trial endpoint and no special payload.

The first request for a given X-SS-Org-Id automatically starts that customer's 30-day trial. No provisioning call, no pre-registration, the trial is created on demand on first use.

---

5. Detecting Trial Status (Response Headers)

SafeSky reports trial state on every response so you never have to do date arithmetic on the client, and so SafeSky can adjust trial duration server-side without a client update.

During the trial (days 1 to 30)

Header	Example	Meaning
X-SS-Trial-Status	active	The trial is currently running.
X-SS-Trial-Days-Remaining	15	Whole days left before expiry.

After the trial expires

Header	Value	Meaning
X-SS-Trial-Status	(absent)	No active trial.
X-SS-Trial-Days-Remaining	0	The trial has ended.

You can implement either a simple presence check (X-SS-Trial-Status present = active) or a countdown display using X-SS-Trial-Days-Remaining.

Why headers instead of dates:

• Zero date calculations on your side.
• SafeSky controls trial duration server-side (and can extend it remotely).
• Works regardless of device clock settings or time zones.
• Trivial to implement: read one header.

---

6. What Happens When the Trial Expires

At expiry, SafeSky deliberately keeps your integration working end-to-end while removing the value of receiving, creating a clear, low-friction upgrade prompt rather than a broken feature.

Endpoint	Behaviour after expiry
POST /v1/uav (share positions)	Continues normally. Drone safety data is never blocked.
GET /v1/uav (receive traffic)	Returns HTTP 200 with an empty traffic payload and X-SS-Trial-Days-Remaining: 0.

Note: Expired GET requests return an empty 200, not an HTTP 402 error. Your integration keeps running normally, the customer simply sees "no traffic" plus the zero-days signal. This is a deliberate choice to nudge conversion rather than break your product.

On expiry, your product should:

1. Detect the absence of X-SS-Trial-Status (or X-SS-Trial-Days-Remaining: 0).
2. Show a clear notice: the trial has ended, position sharing continues, and an API key is required to keep receiving traffic.
3. Reveal/highlight the API key field and link the customer to https://www.safesky-enterprise.com to get a key.
4. Once a key is entered, switch authentication to the customer's own key, reception resumes immediately under their subscription.

---

7. Suggested User Interface

Configuration Panel

┌─────────────────────────────────────────────────────────┐
│  SafeSky Network Integration                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────┐  Enable SafeSky Network                        │
│  │ ON  │                                                │
│  └─────┘  Share drone positions + receive traffic.      │
│           Includes a 30-day free trial.                 │
│           No registration required.                     │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  SafeSky API Key (optional)                             │
│  ┌───────────────────────────────────────────────────┐ │
│  │                                                   │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  Enter your API key to keep receiving traffic after     │
│  the trial. Get your key at safesky-enterprise.com      │
│                                                         │
└─────────────────────────────────────────────────────────┘

Trial-Expiry Notification

┌─────────────────────────────────────────────────────────┐
│  ⚠  Your SafeSky 30-day trial has expired               │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  You're still sharing your drone positions with the     │
│  SafeSky Network.                                       │
│                                                         │
│  To continue receiving traffic data, subscribe at:      │
│  safesky-enterprise.com                                 │
│                                                         │
│  [ Get API Key ]   [ Dismiss ]                          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Copy guidance: make it explicit that enabling the toggle grants a 30-day free trial out of the box and that position sharing remains free forever, only receiving traffic requires a subscription after the trial.

---

8. Security & Best Practices

1. Protect the integration key. It is a shared secret embedded in your application, obfuscate it and never expose it in client-side source that is trivially readable. It can be rotated or revoked by SafeSky independently of your own contract key.
2. One token, one trial, forever. Generate each customer's X-SS-Org-Id once, store it, and never change it (see Section 2 for the full token rules). SafeSky pins the first-seen token per trial and enforces one trial per organization to prevent trial farming (rotating tokens to reset the clock).
3. Never use the integration key anonymously. Always pair it with X-SS-Org-Id; a missing header returns HTTP 400.
4. Don't mix credentials. For a given request, use either the integration key or the customer's own key, never both.
5. Trust the server, not the clock. Trial start, duration, and expiry are computed server-side, so device clocks and client tampering cannot extend a trial. Always rely on the response headers.

---

9. Integration Checklist

• Obtain an integration key from SafeSky and embed it securely in your product.
• Add an "Enable SafeSky Network" toggle plus an optional API key field to your settings.
• Generate a unique, stable, opaque X-SS-Org-Id per customer (store once, reuse forever).
• Send X-SS-Org-Id on every request while using the integration key.
• Sign requests with the same HMAC scheme as a standard SafeSky key.
• Read X-SS-Trial-Status / X-SS-Trial-Days-Remaining on responses to drive UI state.
• On expiry, prompt for an API key and link to safesky-enterprise.com; keep POST sharing on.
• When the customer enters their own key, switch authentication to that key.

---

10. Quick Reference

Item	Value
Trial length	30 days, time-boxed (no usage quota)
Trial scope	Per customer, keyed on X-SS-Org-Id
Auth (trial)	Embedded integration key (HMAC) + X-SS-Org-Id
Auth (post-trial)	Customer's own API key (HMAC)
Share positions (POST /v1/uav)	Always available, free, before, during, and after trial
Receive traffic (GET /v1/uav)	Full during trial → empty 200 after expiry
Integration key, no X-SS-Org-Id	HTTP 400 Bad Request
Trial status headers	X-SS-Trial-Status, X-SS-Trial-Days-Remaining
Get a key / subscribe	https://www.safesky-enterprise.com

---

SafeSky takes care of trial provisioning, metering, and conversion. You embed one key, send one header, and read two response headers.