Developer Guide
Using the Verify Permission API
6.0 Using the Verify Permission API
You can use the Verify Permission API to query an existing Access Token for the Get Location API: either retrieving the Access Token associated with your application for a particular mobile user, or checking the validity of an Access Token that you had stored locally.
The Verify Permission API only works if your application already has permission to locate the given user; it does not grant new permissions.
6.1 Querying Permissions by User
Your application can request the Access Token and token secret for locating a particular mobile user, given the user ID. This is an efficient alternative to the OAuth redirect process for user authorization, as long as permission has already been granted.
To make this request, submit an HTTP GET to the following URL:
https://veriplace.com/api/1.1/permission/users/<userID>/locations
The user ID is the unique Veriplace identifier for the mobile user, the same one that you can obtain from the User Discovery API and pass to the Get Location API. (Note that this URL is identical to the URL for locating a user in the Get Location API, except for the /permission/ prefix.)
The request must be signed using HMAC-SHA1 and the application-specific Access Token (the one configured for your application as a whole, rather than for a particular user).
6.1.1 Successful Requests
On success, you will receive an HTTP 200 ("OK") code, and a response document describing the Access Token and token secret. The default XML encoding is as follows:
<?xml version="1.0" encoding="UTF-8"?> <token value="tokenValue" secret="tokenSecret" xmlns="http://veriplace.com/xml/1.1" />
You can also request a JSON-encoded response by adding the header "Accept: application/json" to the request. The JSON encoding for the response is as follows:
{ "token": { "value": "tokenValue", "secret": "tokenSecret" } }
6.1.2 Unsuccessful Requests
You will receive a HTTP 401 status code if your application does not have permission to locate the user, or 404 if the user ID is unknown.
6.2 Verifying Permissions by Token
If your application has previously obtained and stored an Access Token for locating a user, you may choose to verify that the permission is still valid before using it, since location permission could have been revoked by the end user.
To verify a permission when you already have the Access Token, submit an HTTP GET to the following URL:
https://veriplace.com/api/1.1/permission
Requests must be signed using HMAC-SHA1 and the Access Token representing the permission.
6.2.1 Successful Requests
On success, you wil receive an HTTP 200 ("OK") code.
6.2.2 Unsuccessful Requests
You will receive a HTTP 401 status code if the permission was already deleted or is otherwise invalid.