Developer Guide
Using the User Discovery API
3.0 Using the User Discovery API
The Veriplace User Discovery API lets you discover individual user identifiers.
3.1 About User Discovery
Before using any of the other APIs related to users, you must associate users in your application with a Veriplace identity. This process is known as User Discovery.
User identity is considered a protected resource within Veriplace. There are legal and privacy concerns related to exposing personally identifiable information (PII) to third parties, especially in conjunction with location.
To mitigate these concerns, Veriplace employs a randomly generated user identifier in lieu of all other PII data. Veriplace defines its user-oriented APIs in terms of the user identifier, and never exposes other PII data, such as mobile numbers, email addresses or OpenIDs.
3.2 Obtaining a User Identifier
Your application can obtain a user identifier in one of two ways:
- By supplying known PII data, such as an email address, mobile phone number or OpenID
- By requesting that the user log in to Veriplace
Both types of requests require an HTTP GET or POST to the following URL:
https://veriplace.com/api/1.1/users
Both types of requests must be signed using HMAC-SHA1 and an Access Token, the exact type of which depends on the type of request.
3.2.1 Applications Supply PII Data
If your application users have already supplied their PII data to your application, you can employ the application-specific Access Token to sign a protected resource request for the Veriplace user identity. See section 2.3.1.2 OAuth Credentials for more details. The three examples shown below illustrate protected resource requests for email address, phone number and OpenId, respectively:
- User discovery by email address:
https://veriplace.com/api/1.1/users?email=user@example.com
- User discovery by mobile phone number:
https://veriplace.com/api/1.1/users?mobile=1115551212
Note: A North American mobile number must contain 10 decimal digits, optionally prefixed by "1" or "+1"; all other non-digit characters are ignored, so "4155551212", "+14155551212", and "(415) 555-1212" are all equivalent.
- User discovery by OpenID:
https://veriplace.com/api/1.1/users?openid=user@openid.example.com
Note that the first three steps of the four-step OAuth process are not needed here because the developer obtains the application-specific Access Token during registration.
It is also possible to query for multiple users by PII using multiple email address, mobile phone numbers, or OpenID parameters:
https://veriplace.com/api/1.1/users?mobile=1115551212&mobile=1115551213
To avoid URL length limits, HTTP POST should be used if multiple PII parameters are specified.
3.2.2 Applications Request User Log in to Veriplace
The other option for User Discovery is to redirect the user to Veriplace and have them log in to identify themselves. In this case, Veriplace returns a one-time Access Token, which is used to sign the protected resource request.
For User Discovery, the User Authorization URL must specify the uri parameter as defined below:
https://veriplace.com/api/userAuthorization?uri=https://veriplace.com/api/1.1/users
This approach will not always require a user log in. In some cases the user may already be logged in or may have set a cookie that allows them to avoid login for user discovery.
3.2.3 Common Failure Conditions
User discovery will fail if the user chooses not to log in or if the provided PII are not recognized.
3.2.4 Registering New Users
The User Discovery API handles users who are not currently Veriplace subscribers; users may register during the user authorization redirect; registration will be invisible to your application.
3.2.5 User Discovery Sequence Diagram
There are five steps of communication that occurs between your application and Veriplace during the process of discovering a single user via login. These are illustrated in the sequence diagram below.
The sequence of events illustrated above is described below.
- Your application requests an OAuth Request Token using the Veriplace Request Token URL, which is granted.
- Veriplace redirects your application to the Veriplace user authorization URL for secure authentication.
- Veriplace redirects the User Agent back to your application after the user logs in.
- Your application exchanges the Request Token for an OAuth Access Token, which is granted.
- Your application uses the Access Token to obtain the identity of the user who logged in.
At the end of this process, your Access Token is revoked.
3.3 Successful Requests
On success, you will receive an HTTP 200 ("OK") code and XML content representing the user identifier or user identifiers queried.
If the Application requests that the user login or only one user is queried using PII data, a single result will be returned. The XML encoding of the result is as follows:
<?xml version="1.0" encoding="UTF-8"?> <user id="1378603015410979905" xmlns="http://veriplace.com/xml/1.1" />
If you requested JSON encoding, the same result would be encoded like this:
{ "user": { "id": 1378603015410979905 } }
Alternatively, if multiple PII parameters are specified, a result will be returned for every parameter that was matched to a user identifier. The XML encoding:
<?xml version="1.0" encoding="UTF-8"?> <identifiedUsers xmlns="http://veriplace.com/xml/1.1"> <identifiedUser key="1115551212" keyType="mobile"><user id="1378603015410979905"/></identifiedUser> <identifiedUser key="1115551213" keyType="mobile"><user id="7799817486972445687"/></identifiedUser> </users>
The JSON encoding for a multiple-user result:
{ "identifiedUsers": [
{ "key": "1115551212", "keyType": "mobile",
"user": { "id": 1378603015410979905 } },
{ "key": "1115551213", "keyType": "mobile",
"user": { "id": 7799817486972445687 } }
] }
3.4 Unsuccessful Requests
In accordance with the HTTP Response Codes section of the OAuth specification, you will receive an HTTP 400 ("Bad Request") or 401 ("Unauthorized") code if something went wrong with the OAuth signature. In some cases, a 401 error code will be accompanied by the reason phrase "Invalid / non-monotonic timestamp", which is commonly a sign that your system clock is misconfigured.
In accordance with REST, an HTTP 404 (Not Found) error message is returned if no user could be identified.