Account API – Authentication

Authentication consists of two steps:

  1. Creating a session
  2. Passing the session token with each subsequent request

Creating A Session

An account API key is like a password for your account on devicehq.com. You can generate your account key on devicehq.com by logging in to DeviceHQ, and

To  generate your account key on devicehq.com by logging in to DeviceHQ, and clicking on the email address link on the upper

  1. Log into DeviceHQ
  2. Click the email address link in the upper right hand corner of the page
  3. Click on Account Info
  4. From there you can generate account API keys.

Note:  After creating the key, it will not be shown to you again, as it is stored using a 1-way cryptographic hash algorithm.

By possessing the account API key (not the same as the account key), an API client can access the account with the same privileges as a manager-level user belonging to that account.

To access the API, the first step is to create a session by submitting a valid account API key, which will return a session token that can be used for subsequent requests.

This can be done by making a POST or PUT request with a header field set to “X-API-KEY” or a URL parameter “api_key” set to the account API key.

For example, either of the following three requests would create a session.

NOTE: You must set the Content-Length header for any POST request. Many HTTP clients automatically include this header field on any POST request. If using the first form listed below (no data field sent), you must set a header to “Content-Length: 0“.

Example account API key: 5sHszZNuTfmgs58VGA

POST /api/v2/session?api_key=5sHszZNuTfmgs58VGA
Headers: "Content-Length: 0"
curl -H "Content-Type:application/json" -X POST "https://www.devicehq.com/api/v2/session?api_key=5sHszZNuTfmgs58VGA" -H "Content-Length:0"

or

POST /api/v2/session
{ "api_key": "5sHszZNuTfmgs58VGA" }
curl -H "Content-Type:application/json" -X POST https://www.devicehq.com/api/v2/session -d'{"api_key": "5sHszZNuTfmgs58VGA"}'

or

POST /api/v2/session
Headers: "X-API-KEY: 5sHszZNuTfmgs58VGA"
curl -H "Content-Type:application/json" -X POST https://www.devicehq.com/api/v2/session -H "X-API-KEY: 5sHszZNuTfmgs58VGA"
  • After creation of a valid new session, any existing session for the account that was open will be closed and the new session will replace it. An account can only have one session open at a given time.
  • The response to either of the above requests will be json formatted as follows:
 "meta":{
    "token": "<session_token>", 
    "expires":"", 
    "jsonapi": {"version":"1.0"}
  }

The token will be a short string of approximately 14 characters. Subsequent requests to the api will be honored if the token is included either as a url request parameter “token” or as a header field “X-AUTH-TOKEN”

  • Sessions expire 5 minutes after the last request to the server.
  • The session may also be closed with the following route (the token must be included as with all other requests):
DELETE /api/v2/session