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):
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 |
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.
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]
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.