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 server-side (explicit grant) flow. GovX also supports the client-side (implicit 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, you're reading the right document.
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, please refer to our implicit grant flow implementation guide.
Getting Started
Before you start configuring the OAuth explicit 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 Explicit 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 explicit 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 server-side (explicit) flow this should always be code. |
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=code&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. Receive the authorization code @ redirect_uri
Once the user has completed registration / verification and granted access to your listing, they will be redirected back to your redirect_uri with the authorization code and state in the query string.
https://dev.govx-oauth.com/callback?code={code}&state={original_state}
You will use this code to obtain an access token for our API. It is a single-use code that is valid for 5 minutes.
Error States
If the user chooses to deny access or an error occurs, the error code and description will be appended to the URL in place of the access code. The format will look as follows:
https://dev.govx-oauth.com/callback?error={errorCode}&error_description={errorDescription}
Error Code | Error Description |
---|---|
invalid_request | The request contains invalid data. Most commonly this happens if you may be missing a required parameter (like scope, redirect_uri or response_type) or you're requesting a redirect_uri string that does not match the Whitelisted URL. |
invalid_client | The client ID is not valid. |
invalid_scope | Either the scope requested is unknown, or the client is requesting a scope they do not have access to. |
invalid_response_type | An unknown response type has been requested. |
access_denied | The user has denied access to their data. |
3. Exchange the authorization code for an access token
You will grab the code from the URL query string and send a request to our token endpoint.
POST https://auth.govx.com/oauth/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}
&redirect_uri={original_redirect_uri}
&code={code_from_response}
&client_secret={secret_key}
&grant_type=authorization_code
Name | Required | Description |
---|---|---|
client_id | YES | Your client ID must match the ID used in the initial authorization request. |
redirect_uri | YES | This must match (exactly) the URL from the original request. |
code | YES | The code received in the previous calls. |
client_secret | YES | Your secret key |
grant_type | YES | authorization_code
This is the only value supported for this method. |
This will retrieve a JSON payload containing an access_token. The token expiration is contained in the payload.
{
"access_token" : "token",
"token_type": "bearer",
"expires_in" : 600
}
If the exchange is unsuccessful for any reason, it will return a 400 status code with payload as follows:
{
“code”: “access_denied”,
“description”: “Authorization has been denied for this request.”
}
4. Request user data
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
5. 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.