GW-API: Auth keys

Gateway API Home

API Navigation

• Authentication
  • API Auth Key
• Provided resources
  • Commands
  • Devices
  • Device commands
  • Gateways

See also
Managing authentication keys

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:

• curl
• python
• output

  <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:

• curl
• python
• output

  <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.