GPS Data Web Service API

Authentication

Access to your GPS tracker data, as well as your geographical zones and other personalized data, is kept private to your account. So we need you to authenticate each request you make.

Currently, we support a token-based authentication scheme, HTTP Basic and HTTP Digest Authentication.

There are three URLs provided specifically for authentication:

This table illustrates how the authentication URLs behave. Making a GET request without having authenticated will prompt for credentials. For the token, you can POST your username and password to retrieve the token. In all cases, successful authentication will return an HTTP redirect to the gateway, which also happens as a result of an authenticated GET request.

URL Ending GET, unauthenticated POST, unauthenticated GET, authenticated
token HTTP 401
WWW-Authenticate: X-Token
(Custom Authentication)
Parameters (data object properties):
  • username
  • password
  • duration (up to 86400, optional)
  • key (replaces username/password)
Success: Redirect to gateway
Failure: 400 (bad credentials)
Redirect to gateway
auth-basic HTTP 401
WWW-Authenticate: Basic
HTTP 405 Method Not Allowed Redirect to gateway
auth-digest HTTP 401
WWW-Authenticate: Digest
HTTP 405 Method Not Allowed Redirect to gateway

HTTP Authentication

The web service supports both Basic and Digest Authentication, with the same username and password as submitted when retrieving a token. These HTTP Authentication methods are documented extensively elsewhere and should be implemented in your HTTP library.

Token

A token is a time-limited key that you can send along with your HTTP request to authenticate. A token can last up to a maximum of 24 hours, and can be revoked at any time - in which case you need to get a new one.

The token-based scheme we use also includes a Set-Cookie header in the response, so if your client supports the use of cookies, the token will persist across requests in that manner. However, cookies are not required to access any of the functionality of the web service.

You can obtain a token by making POSTing to the URL in gateway.token_url. The POST request must include either your web service key (parameter "key") or a username and password (parameters "username" and "password"). The response will be a redirect to the gateway, or a 400 Error code if the client could not authenticate (e.g. bad password). Below is an example of what the request/response cycle might look like when obtaining a token.

POST /rest/v2/token HTTP/1.0
Host: mygink.com
Content-type: application/json
Content-length: 62

{"username": "j.random.user", "password": "j.random.password"}
HTTP/1.0 303 See Other
Location: gateway?_token=[token]
Set-Cookie: token=[token]; expires=Fri, 01-Apr-2011 12:00:00 GMT

Here, the server has requested a redirect. We do this so that we can detect whether the client is using cookies on the next request.

GET /rest/v2/gateway?_token=[token] HTTP/1.0
Host: mygink.com
Accept: application/json
Cookie: token=[token]
HTTP/1.0 200 OK
Content-type: application/json
...

[gateway object, token_valid = TRUE]

Try it out

If you have a username and password, you can view the available data right here in your browser. Feel free to browse the data on our demo account - the fields are already filled in below.

HTML Data Browser