Skip to main content
For the complete documentation index, see llms.txt.

Hubble Network developer documentation: integrate Bluetooth devices with terrestrial and satellite connectivity.

Hubble Platform API

The Hubble platform is built API-first. Use our Cloud API to manage your devices and access device data programmatically. We've designed our API following RESTful principles. Each endpoint returns standard HTTP status codes and may include JSON payloads.

API Access​

Use API Keys to authenticate with the Hubble Cloud API for your organization.

Generate an API Key​

Log in to your Hubble dashboard. Navigate to Developer Tools > API Tokens to create a new API Key. Provide a name for the token, and set an appropriate expiration date for temporary access.

Organization ID​

You will need org_id to make API requests. From your Hubble dashboard, navigate to Developer Tooks > API Tokens, or Organization Settings, to find your Organization ID.

Authorization Scopes​

API endpoints require specific authorization scopes to perform the intended operation. Required Scope is always provided in the API documentation.

API Keys can be created with specific authorization scopes that control what operations the key can perform. If no scopes are specified, the key will be created with all available scopes (admin-level access).

ScopeAccess
read-api-keysView API keys and their metadata
write-api-keysCreate, update, and delete API keys
read-usersView user information and roles
write-usersAdd, update, and remove users from the organization
read-organization-metadataView organization details and settings
write-organization-metadataUpdate organization information
read-devicesView device information and status
write-devicesRegister and manage devices
read-invitationsView pending invitations
write-invitationsCreate and revoke user invitations
read-packetsAccess packet data and retrieval endpoints
read-platform-metricsView platform metrics and analytics
read-billing-usageView billing usage information
read-billing-invoicesView billing invoices
read-webhooksView webhook configurations
write-webhooksCreate and manage webhook endpoints
read-satellitesView satellite ephemeris and pass data

Example Scope Combinations

  • Create a key with read-only access: ["read-api-keys", "read-users", "read-devices"]
  • Create a key for device management: ["read-devices", "write-devices"]
  • Create a key for user management: ["read-users", "write-users", "read-invitations", "write-invitations"]

Best Practices for Data Security

  • Create keys with the minimum required scopes for your use case
  • Regularly review and rotate API keys
  • Use descriptive names for your keys to track their purpose
  • Set appropriate expiration dates for temporary access

Import API Definition​

You can quickly import the Hubble Cloud API into your preferred developer environment (such as Postman or Insomnia) using our public OpenAPI definition. Simply download or import the YAML file directly:

https://hubble.com/docs/openapi.yaml

Pagination​

When the number of objects requested exceeds the maximum page size for an endpoint, the API response will be paginated. This means you will receive a subset of the total results, along with a Continuation-Token in the Response Header that can be used to fetch subsequent subsets.

To retrieve the next set of data, you must use the provided Continuation-Token in the Request Header of your next API call to the same endpoint. Continue using the provided token in each successive request until no Continuation-Token is returned, which indicates you have retrieved all available data.

Rate Limits​

The Hubble Cloud API follows a leaky bucket approach to rate limiting. Each endpoint is limited to roughly two (2) requests per second, and your organization is limited to roughly five (5) requests per second in total, across all endpoints. These figures are scaled by your organization's plan tier, so higher tiers receive proportionally higher limits. If you exceed a limit, you will receive a 429 status code. We recommend backoff retry logic to stay within the limit.

Request Headers​

All HTTP responses will include a X-Request-ID header that is logged internally and can be used for tracing/debugging a particular API request. All HTTP requests can include a X-Request-ID header which will be logged and mapped to the responses' X-Request-ID header.

Share Request Headers whenever troubleshooting an API issue with Hubble Support.

Status Codes​

The Hubble Cloud API returns the following HTTP status codes: 200, 400, 401, 403, 404, 413, 429 and 500. Use the tailored message returned with each status code for insight in the specific context of the endpoint you are attempting to access.

Versioning​

Our cloud backend follows a rolling release model. This means:

  • Continuous Deployment: New features, security updates, and performance improvements are automatically rolled out.
  • Backward Compatibility: Cloud updates are designed to be compatible with devices running firmware/SDK versions within our active or maintained support windows.
  • Transparent Change Management: Release notes and changelogs are published regularly so you can track enhancements and understand any adjustments that might affect integrations.
  • Versioned Public API: The Cloud API uses basic major versioning in the url paths (/v1/..., /v2/... etc.). Major backwards incompatible changes will be made by creating a version of the endpoint with a higher version and communicating with customers to migrate. The legacy /api/... and /api/v2/... paths remain fully supported as aliases for /v1/... and /v2/... respectively, so previous versions will be supported for a minimum of 1 year.

Authentication​

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT