Go to Qubit

Opentag documentation

Web API – Authentication

API v1 requests are authenticated using the HTTP cookie header. In the future other forms of authentication such as key/token based mechanisms may be made possible.

Cookie Generation

Authentication cookies can be generated by making a post request to the login endpoint. Note the encryption/hashing requirements on the password below.

Request

POST https://opentag.qubitproducts.com/QDashboard/qdashboard/login?username={username}&password={password}

Property Type Description
username string Account username
password 28 byte SHA1 base64 string The password should be hashed with SHA1 and outputted in base64. Note that this is not the same as base64 encoding the hex output of SHA1; the raw output of the SHA1 digest itself has to be encoded.

Response

The login endpoint responds with a JSON object indicating success/failure.

Success

{"msg":"","status":"OK","errorCode":null}

Failure

{"msg":"username or password is incorrect","status":"FAIL","errorCode":null}

On success several Set-Cookie HTTP headers will be sent:

Cookie Example Description
ci 77354 Client ID
cn example_user@testing.com Client name
un example_user@testing.com User name
ui 83288 User ID
si a87mf9ngz4zxMvVnn1AcBGrRvQ Session ID – invalidates after 30 minutes
sk EkZFs32sf631zGRMK8z4niRmT0 Session key – invalidates after 5 minutes

Cookie Regeneration

As you can see in the table, the si and sk cookies both become invalid after a set period of time. It is therefore necessary to refresh both of these parameters at least every 5 minutes. This can be done by making a request to the regeneration endpoint with the cookies generated by the login route:

POST https://opentag.qubitproducts.com/QDashboard/qdashboard/genskey

The genskey route responds with the same JSON as the main login route, the only difference being it only sets the si and sk cookies. If the request fails, you will need to hit the login route again to get a full new set of authentication cookies.

Changing client/account

In Opentag, each user as effectively their own ‘Client’. This means that your session cookies are only valid for your own client and to access another account you have to generate separate session cookies.
Important: you must have already authenticated using the login endpoint before attempting to authenticate with another account.

To change account, make a request to the client endpoint with the cookies acquired from the login endpoint and the ID of the client you wish to change to:

PUT https://opentag.qubitproducts.com/QDashboard/qdashboard/user/current/client?clientId={clientId}

The response will contain an entire set of new cookies, like in the table above, which can then be used for the specified client.

Examples

The following examples show how to authenticate with Opentag using cURL on the command line.

Login

Request

curl -v -X POST 'https://opentag.qubitproducts.com/QDashboard/qdashboard/login?username=example_user@testing.com&password=QsWWElI24nT9GwtT2AyKp0vdqYv='

Response

 HTTP/1.1 200 OK
  Date: Fri, 26 Sep 2014 09:07:38 GMT
  Server: Apache
  Set-Cookie: si=7l6KHxBt1R6Nfwi91PyKTwc6II; Path=/
  Set-Cookie: sk=BGH8GtgpZlDpAhqVU6X5a1RQUqk; Path=/
  Set-Cookie: ci=83288; Path=/
  Set-Cookie: cn="example_user@testing.com"; Version=1; Path=/
  Set-Cookie: ui=83288; Path=/
  Set-Cookie: un="example_user@testing.com"; Version=1; Path=/
  Content-Language: en-US
  Content-Length: 42
  Content-Type: text/html;charset=ISO-8859-1

Regeneration

Request

curl -v --cookie 'ci=83288; cn="example_user@testing.com"; ui=83288; un="example_user@testing.com"; si=0vp9J86daQ0OWleqyBq8HSL0d3c; sk=HoI5kvLc5cvstEEtjFY4pz86n8M' -X POST https://opentag.qubitproducts.com/QDashboard/qdashboard/genskey

Response

 HTTP/1.1 200 OK
  Date: Fri, 26 Sep 2014 09:24:11 GMT
  Server: Apache
  Set-Cookie: si=0vp9J86daQ0OWleqyBq8XSL0d3c; Path=/
  Set-Cookie: sk=g5u3oq2m8YCCFJWchmTCTUzJ4T8; Path=/
  Content-Language: en-US
  Content-Length: 42
  Content-Type: text/html;charset=ISO-8859-1

Change client

Request

curl -v --cookie 'ci=83288; cn="example_user@testing.com"; ui=83288; un="example_user@testing.com"; si=0vp9J86daQ0OWleqyCq8XSL0d3c; sk=g5u3oq5m8YCCFJWchmTCTUzJ4T8' -X PUT https://opentag.qubitproducts.com/QDashboard/qdashboard/user/current/client?clientId=77354

Response

 HTTP/1.1 200 OK
  Date: Fri, 26 Sep 2014 09:29:03 GMT
  Server: Apache
  Set-Cookie: si=y9YLVrYtPWiebMI8fk4wg5pHnc; Path=/
  Set-Cookie: sk=q0jjuTXUgyj8qphCUESGu1kz4; Path=/
  Set-Cookie: ci=77354; Path=/
  Set-Cookie: cn="example_user@testing.com"; Version=1; Path=/
  Set-Cookie: ui=83288; Path=/
  Set-Cookie: un="example_user@testing.com"; Version=1; Path=/
  Content-Language: en-US
  Content-Length: 5
  Content-Type: text/html;charset=ISO-8859-1

Was this helpful?