Integration Partner API

The IDI Fly v3 Integration API lets third-party integration partners interact with the IDI Fly drone command-and-control platform. It exposes:

• Job management — create and manage drone mission requests.
• Stream sharing — generate shareable links for live device streams and telemetry.
• Resource access — query the device groups available to your organisation.
• Real-time updates — subscribe to (and publish) live telemetry over WebSocket.

All access is machine-to-machine: there is no end user in the loop. Each partner authenticates with their own credentials and only ever sees resources belonging to their organisation.

---

Base URLs

Type	URL
REST API	https://api.idi-fly.com
Token endpoint	POST https://api.idi-fly.com/v3/auth/token
WebSocket	wss://api.idi-fly.com/telemetry

---

Authentication

The API uses the OAuth 2.0 client_credentials grant (machine-to-machine). Each partner is issued a dedicated Amazon Cognito App Client:

• client_id — the App Client ID
• client_secret — the App Client secret
• A set of pre-configured scopes that define the partner's access level

Authentication flow

How the two layers work

Layer	Purpose	Header
API key	Protects the token endpoint (rate limiting / abuse prevention)	x-api-key: <api-key>
JWT bearer token	Authorises every other endpoint	Authorization: Bearer <token>

Getting an access token

curl -X POST https://<API_ENDPOINT>/v3/auth/token \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'

Response

{
  "access_token": "eyJraWQiOiJEaWVoK0U0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

:::tip Scopes are not requested by partners Your access level is determined by the scopes configured on your App Client. You do not pass a scope parameter — Cognito grants exactly the scopes assigned to you. :::

Using the token

curl -X GET https://<API_ENDPOINT>/v3/jobs \
  -H "Authorization: Bearer <access_token>"

Token renewal

Tokens are valid for 1 hour (3600 seconds). The client_credentials grant does not issue refresh tokens — simply request a new token when the current one expires. This is standard for M2M authentication.

---

Access scopes

Endpoints are protected by OAuth scopes. Your scopes are agreed during onboarding and assigned to your App Client.

Scope	Grants access to
command:create	POST /v3/jobs/create
command:read	GET /v3/jobs, GET /v3/jobs/{jobId}
command:update	PATCH /v3/jobs/{jobId}, DELETE /v3/jobs/{jobId}, POST /v3/jobs/{jobId}/cancel
stream:share	POST /v3/streams/share
stream:publish	Publishing telemetry over the WebSocket API
share:read	GET /v3/shares, GET /v3/shares/{shareCode}
share:manage	DELETE /v3/shares/{shareCode}
resources:read	GET /v3/resources

Resource server identifier: https://api.idi-fly.com

When requested explicitly (e.g. when calling Cognito directly), scopes are namespaced under the resource server, for example https://api.idi-fly.com/command:read.

---

Onboarding

To become an integration partner you will be provided with:

1. Cognito App Client ID and Client Secret (machine-to-machine, client_credentials grant).
2. The API key for the token endpoint (x-api-key).
3. Your REST and WebSocket endpoint URLs for the target environment.
4. The resource server identifier (https://api.idi-fly.com) and your assigned scopes.

Once you have credentials:

1. Call the token endpoint to obtain an access token.
2. Use the token as a Bearer credential against the REST API.
3. Open a WebSocket connection for live telemetry.

The fastest way to explore is the Postman collection, which has ready-made requests for every endpoint.

---

Error format

All errors return JSON. Authentication errors follow the OAuth 2.0 convention:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Resource endpoints return a simpler shape:

{
  "error": "Job not found"
}

Status	Meaning
400	Missing or invalid parameters
401	Missing, invalid, or expired token (or invalid client credentials)
403	Authenticated but lacking the required scope, or accessing another org's resource
404	Resource not found
405	Method not allowed for that route
500	Internal server error

See the REST API Reference for per-endpoint details.