API Basics
All Helios API methods require valid authentication and are protected using the OAuth 2.0 client credentials flow. The general process for authenticating requests involves first requesting an access token using the developer API key pair, and then requesting protected data using the access token. Contact the Helios Sales Team if you would like to obtain an API key.
Request an access token
To receive an access token, a client submits a request to the Helios Authentication API with the API key pair. The API key pair can either be specified using an HTTP Basic Authorization header or as part of the request body.
The Authorization header is computed by base64 encoding the client_id
and client_secret together with a colon separating them. In
pseudo-code, this looks like:
result = base64Encode(client_id:client_secret) // e.g. MTIzQUJDOnNlY3JldA==
With the Authorization header computed, the client can make a POST request to the access token method. An additional parameter must also be included in the POST body to tell the Helios API to use the OAuth client credentials grant type. Using curl, the token request looks like this:
curl -H "Authorization: Basic MTIzQUJDOnNlY3JldA==" -X POST https://api.helios.earth/v1/oauth/token -d "grant_type=client_credentials"
Alternatively, the API key pair can be specified directly in the request
body using the client_id and client_secret
parameters.
curl -X POST https://api.helios.earth/v1/oauth/token -d "grant_type=client_credentials&client_id=key_id&client_secret=key_secret"
If the request is successful and the API key pair is valid, the Helios API will provide a JSON response that includes the access token:
{"access_token": "..."}
The access token is a JSON web token (JWT), which provides time-limited access to the resources that are available to the client.
Request data from protected API methods
Once the access token has been obtained, it can be used to authenticate requests against protected API methods. The access token can be specified in the Authorization header of the request, in the body of a POST/PUT/PATCH request, or as part of the query string in the URL.
To include the access token in the request header, use the Authorization header with the Bearer type:
curl -H "Authorization: Bearer ...access token..." https://api.helios.earth/v1/cameras
To include the access token in the request body, include the
access_token parameter:
curl -X POST https://api.helios.earth/v1/cameras/_search -d "access_token=...access token..."
To include the access token in the URL, include the access_token
query string parameter:
curl https://api.helios.earth/v1/cameras?access_token=...
Optional request parameters
Some API routes allow optional parameters to be sent along with the request. For GET requests, these additional parameters are sent using the query string. For example, to include query parameters in an alerts search, the request may look like this:
https://api.helios.earth/v1/alerts?event=tornado&state=texas
The search/index methods in the core APIs can also be accessed using POST
requests. This is useful in certain cases, since there is a limit on the size
of HTTP GET query strings. When submitting requests using POST requests, the
query parameters can either be specified as JSON or as form encoded values.
The Content-Type header must be set appropriately to either
application/json or x-www-form-urlencoded so the
API can properly parse the parameters.
Example of posting search parameters as JSON:
POST https://api.helios.earth/v1/alerts/_search
Content-Type: application/json
{"event": "tornado", "state": "texas"}
Example of posting search parameters as form encoded:
POST https://api.helios.earth/v1/alerts/_search Content-Type: x-www-form-urlencoded event=tornado&state=texas
Refresh the access token
Since the access token is time-limited, in order to make continued requests over a large period of time, new access tokens will need to be requested using the same process described above.
Depending on your application, you can choose to refresh your token using
an automated process (e.g. cron) or just have your application obtain a
new token after the current token has expired. The
Current User method in the
Authentication API will return an expires_in attribute to let
you know how long your current access token is valid.
New access tokens requested from the Authentication API are valid for 7 days.