Account API – Authentication

  • Authentication consists of two steps:
  1. Creating a session.
  2. Passing the session token with each subsequent request.

To access the API, create a session by submitting a valid account API key, which will return a session token that can be used for subsequent requests. For help generating account API keys, refer to Generating API Keys

Create a session 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, any of the following three requests would create a session.
Note: You must set the Content-Length header for any POST request. Many http clients will 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"

Creating a valid new session closes any existing session for the account that was open. The new session replaces it. Accounts can only have one open session at a time.

  •  The response to any of the above requests will be json formatted as follows: 
    "meta":{
"token": "<session_token>",
"expires":"<ISO formatted date string >",
"jsonapi": {"version":"1.0"}
}

The token is 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