Overview
The GovX OAuth verification solution allows you to verify a user's group affiliation in real-time. It can be used to identify and target specific customers for special benefits and offers.
We use OAuth 2.0, which is the industry-standard protocol for authorization. If you're not familiar with the OAuth 2.0 protocol, we recommend that you start by reading this guide before diving into our documentation.
This document covers the implementation for the client-side (implicit grant) flow. GovX also supports the server-side (explicit grant) flow. If you're unsure which flow is right for you, keep reading.
Which OAuth flow should I use?
There are two ways to deploy the GovX verification app using OAuth: the explicit grant flow or the implicit grant flow. The method you choose largely depends on whether your application is server-side or client-side.
Explicit grant flow
If your application is executing on a server then you will likely use the explicit flow. In the explicit flow, your app retrieves an authorization code which is then exchanged for an access token. This is considered the most secure method because the access token is passed directly to the webserver hosting your application. The token is never exposed to the user's browser.
If this describes your application architecture, please refer to our explicit grant flow implementation guide.
Implicit grant flow
If your application is a single-page app, meaning it runs in a browser using a scripting language like Javascript, then you will need to use the implicit flow. In this case, instead of getting an authorization code that is exchanged for an access token, your application retrieves the access token directly. While is this more efficient (fewer round-trips), it also means the access token will be exposed on the client-side.
If this describes your application architecture, you're reading the right document.
Getting Started
Before you start configuring the OAuth implicit flow, you'll need to do the following:
- Get access to the GovX Partner Admin portal. You'll receive an invite from your GovX Account Manager.
- Configure your listing, including the display and messaging settings
Once you've completed these steps, you're ready to start configuring your Verification URLs. Our team will walk you through this process and is available to answer any questions you may have.
OAuth Implicit Flow Overview
GovX uses the OAuth 2.0 protocol to provide access to our API. You will use our API to retrieve a user's group affiliation data. The following is a step-by-step guide to deploying verification via the OAuth implicit grant flow.
1. Direct users to the authorization endpoint
In order to initiate the OAuth process, your application must direct the user to the GovX authorization endpoint via a verification link. The easiest way to create properly formatted verification links is to use the link builder tool in the GovX Partner Admin portal. If you do not yet have access to the portal, please contact your GovX account manager.
The following parameters are defined in the verification link (i.e. the authorization endpoint URL).
Name | Required | Description |
---|---|---|
client_id | YES | The client ID associated with the listing |
redirect_uri | YES | Where the user is redirected after authorization. This must be registered with GovX ahead of time and is validated against a white-list for the client ID. |
scope | YES | The scope being requested. There are three types of scope: user_profile, verification, user_demographics. The data contained in each scope is detailed in section 4 below. You can pass multiple scope keys in a single request, as shown in the example url structure below. |
response_type | YES | For the client-side (implicit) flow this should always be token. |
state | NO | This is optional, this value will be passed back to the redirect_uri. |
display | NO | Identifies whether you want to launch the GovX verification application as a full-page or pop-up. Acceptable values are 'full' or 'popup'. If no value is passed, the application will default to 'full'. |
goto | NO | Identifies whether the GovX verification application should open to the login page (better for returning customers) or the registration page (better for new customers). Acceptable values are 'login' or 'register'. If no value is passed, the application will default to 'register'. |
campaign_id | NO | Identifies the campaign, if applicable. Campaigns apply custom settings to the verification funnel. Learn more |
So, an example authorization endpoint will look like this (with placeholders for real values):
https://auth.govx.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=user_profile%20verification%20user_demographics&response_type=token&state={state}&display=full&goto=register&campaign_id={campaign_id}
For tips on how to format the display on your website, check out this help article.
2. Request user data
After verification, the user is redirected to your app with the access token in the hash fragment of the URL. Your app will need to extract the token from the hash fragment and then make a GET request passing the token as part of the Authorization Header with the Scheme Bearer.
GET https://auth.govx.com/api/data
Authorization: Bearer {token}
Accept: application/json
3. Parse data response
The server will then respond based on the data requested in the scope. The following are some sample responses based on the user's verification status.
Approved Request
The following would be a response for a user with an approved affiliation.
{
"userProfile" : {
"id": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"username": "test@govx.com",
"email": "test@govx.com",
"firstName": "Test",
"lastName": "McTesting"
},
"userDemographics" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"gender": "Male",
"phoneNumber": "1112223333",
"dateOfBirth": "1981-02-15T00:00:00Z"
"zipCode": "92121"
},
"verification" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"occupations": [{
"id": 94,
"path": "law-enforcement/fbi/current",
"key": "current",
"name": "Current employee"
},
{
"id": 93,
"path": "law-enforcement/fbi",
"key": "fbi",
"name": "Federal Bureau of Investigation (FBI)"
},
{
"id": 83,
"path": "law-enforcement",
"key": "law-enforcement",
"name": "Law Enforcement"
}],
"status": "Approved"
}
}
Pending Request
The following would be a response for a user with a pending verification. New verification requests are placed in a pending state if they require manual review by the GovX team.
A user with a pending status is not approved and therefore should not be eligible for your offer. You should message accordingly in your app.
{
"userProfile" : {
"id": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"username": "test@govx.com",
"email": "test@govx.com",
"firstName": "Test",
"lastName": "McTesting"
},
"userDemographics" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"gender": "Male",
"phoneNumber": "1112223333",
"dateOfBirth": "1981-02-15T00:00:00Z"
"zipCode": "92121"
},
"verification" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"occupations": [ ],
"status": "Pending"
}
}
Failed Request
The following would be a response for a user that failed verification in our system. A user with a failed status should not be eligible for your offer. You should message accordingly in your app.
{
"userProfile" : {
"id": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"username": "test@govx.com",
"email": "test@govx.com",
"firstName": "Test",
"lastName": "McTesting"
},
"userDemographics" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"gender": "Male",
"phoneNumber": "1112223333",
"dateOfBirth": "1981-02-15T00:00:00Z"
"zipCode": "92121"
},
"verification" : {
"userId": "ecffdd04-bb49-4e8a-b561-2737238ac31d",
"occupations": [ ],
"status": "Failed"
}
}
userProfile
Name | Type | Description |
---|---|---|
id | string | The ID of the user |
username | string | The username the user uses to log in to the system |
string | The user's email address | |
firstName | string | The user's first name |
lastName | string | The user's last name |
userDemographics
Name | Type | Description |
---|---|---|
userId | string | The ID of the user |
gender | string | The user's gender |
zipCode | string | The user's postal-code |
phoneNumber | string | The user's 10-digit phone number |
dateOfBirth | string | The user's date of birth |
verification
Name | Type | Description |
---|---|---|
userId | string | The ID of the user |
status | string | The aggregate status of the user. Possible values include:
|
occupations | Occupation [ ] | An array of approved, eligible occupations for the user |
occupation
Name | Type | Description |
---|---|---|
id | int | The ID assigned to the occupation |
path | string | A unique path assigned to the occupation. This contains the full path from the parent to the current child. |
key | string | A unique key (per path) assigned to an occupation. |
name | string | The name of the occupation |
Click here to view a comprehensive list of affiliations verified by GovX.
It is possible for a single user to have multiple affiliations (for example, a Veteran that is now a Police Officer). In that case, we will return all eligible affiliations in the JSON response.
If an error occurs while requesting the user data, the system will return a 400 status code response. Handling this error is up to the receiving app, however, we recommend sending the user back to the original authorization end-point (i.e. step 1).
Comments
0 comments
Please sign in to leave a comment.