Skip to main content

Authenticate requests

Most HeliumGeek endpoints require an API key. The key identifies your tenant and enforces the usage plan that applies to your account.

Create an API key​

  1. Review the available plans at heliumgeek.com/api.
  2. Email info@heliumgeek.com with the plan you'd like to activate and the technical contact who should receive credentials.
  3. We will provision the API key for your tenant and deliver it securely. Treat the key like a password—anyone with the value can exercise your quota.

Key lifecycle (including rotation or revocation) is managed by the HeliumGeek team. Contact us whenever you need to update or retire a credential.

Send the key on every request​

Provide the key through the x-api-key header. All responses are returned as JSON by default, so curl is often enough for quick tests:

curl https://heliumgeek.com/v0/gateways \
  -H 'x-api-key: <your api key>' \
  -H 'Accept: application/json'

Client libraries follow the same pattern. For example, using fetch:

const response = await fetch('https://heliumgeek.com/v0/gateways/11xxx', {
  headers: {
    'x-api-key': process.env.HELIUM_API_KEY!,
    'Accept': 'application/json',
  },
});

Authenticate on behalf of a user​

Embedding API keys inside distributed client apps is risky. If you need delegated credentials (for example, short-lived JWTs) contact info@heliumgeek.com so we can discuss the appropriate authentication mechanism for your deployment. The HeliumGeek mobile apps use bespoke flows that can be extended to partners on request.

Best practices​

  • Store secrets securely – prefer a cloud secret manager or encrypted environment variables.
  • Limit distribution – only the services that call the API should have access to the key. Avoid baking it into client-side code.
  • Log usage – capture the quota headers described in the Usage guide to understand how quickly you are consuming capacity.
  • Fail fast – 401/403 responses usually mean an invalid key or a key that does not include the required scope.

Next, review the Pagination and Usage telemetry guides to handle larger result sets and monitor quota status.