GW-API: Auth keys
- Authentication
- Provided resources
See also | |
---|---|
Summary
An authentication key must be sent with all requests for the gateway API service to accept the request. The authentication key can be submitted as either a header or as part of the query string.
To create an authentication key, see the web interface authentication keys documentation.
Usage
The API Auth key can be provided using two methods, however, the header method is the preferred method (see 'As a query string' section for explanation).
- In the HTTP request header as 'x-auth-key' or 'x-api-auth'.
- Within the query string: https://gateway.example.com/api/v1/devices?_auth_key=KEYVALUE
should be submitted in the header as either 'x-auth-key' or ‘x-api-auth’. For example: x-auth-key: xyz987abc123
In the HTTP Header
For security, the preferred method to provide the authentication key is via the HTTP headers as either 'x-auth-key' or 'x-api-auth'. An example:
<div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-auth: abc123xyz789" \
https://myhouse.exmample.com/api/v1/command
<div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests
url = 'https://myhouse.exmample.com/api/v1/command'
headers = {
'x-api-key': 'abc123xyz789',
}
response = requests.get(url, headers=headers)
the_data = response.json() # create a dictionary from results
<div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
No json example found.
As a query string
The authentication key can be provided in the query string using either '_auth_key' or '_api_auth'. However, for security reasons, you should use the HTTP header method. If the authentication key was typed in the command line, it may be retained in your command line history. Also, the web interface logs access requests and may include the query string as part of that logging.
Query string example:
<div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
https://myhouse.exmample.com/api/v1/command?_auth_key=xyz987abc123
<div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests
url = 'https://myhouse.exmample.com/api/v1/command?_auth_key=xyz987abc123'
response = requests.get(url)
the_data = response.json() # create a dictionary from results
<div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
No json example found.