OAuth Integration Guide

Upon application registration, you will immediately have access to the application details page which will list the client_id and client_secret needed to configure your OAuth client.

Overview

ID.me uses OAuth to provide authorized access to its API. We currently use OAuth 2 draft-22. This section describes how you can use the OAuth 2 protocol to to gain access to a user's group affiliation data. Requests to retrieve user data require an access_token that is used to query ID.me's REST API. These tokens are unique to a user and should be stored securely. Access tokens expire 5 minutes after being issued.


The following diagram shows an overview of the OAuth flow. The "RP" in this diagram stands for "Relying Party", a.k.a the partner.

Oauth flow

Getting an access token

In order to get an access_token you must do the following:

  • Direct the user to ID.me's authorization endpoint
    • If the user is not signed in they will be asked to sign in or sign up.
    • After verifying their group affiliation the user will be asked to grant access to your app.
  • After access is granted, the server will redirect the user to your redirect_uri and you can retrieve the access_token in one of two ways:
    • Server-side (authorization code flow): Take the provided code parameter in the redirect and exchange it for an access_token by POSTing the code to our access token request endpoint.
    • Client-side (access token flow): Instead of handling an authorization code, we include the access_token as a fragment (#) in the redirect. This method allows applications without any server component to receive an access_token with ease.

Group Affiliation Verification

Using ID.me's verification technology, partners may leverage digital identity and target the following affinity groups with special benefits or offers.


Group Credential Name
Military Troop ID
Students Student ID
First Responders Responder ID
Teachers Teacher ID
Government Government ID
Employee Employee ID
Alumni Alumni ID

Integration Options

ID.me's technology is designed to be flexible and scalable. Our partners are able to integrate ID.me anywhere to cater to their specific requirements and user experiences. Below you will find integration options that suit multiple user experiences, our In Cart/Checkout Full Integration being our most popular option.


In Cart/Checkout Full Integration In Cart/Checkout Hosted Solution Within Account SSO Landing Page In-Store
Seamless UX new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases
Increased Loyalty/Repeat Purchases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases
Increased New-to-File Shoppers* new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases
Increased Conversion Rates new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases new_releases
Reduced Operational Costs Yes Yes** Yes Yes Yes Yes
Valuable Data for CRM and Retargeted Marketing Yes No Yes Yes Yes Yes
Time to Integrate 3 days < 1 day 3 days 3 days 3 days 3 days
Attracts ‘Pre-Verified’ Users Yes Yes Yes Yes Yes Yes
Prevents Duplicate Accounts Yes Yes Yes Yes Yes Yes
Can Prompt Re-Verification Yes Yes Yes Yes Yes Yes

new_releases new_releases new_releases = Large Impact

new_releases new_releases = Moderate Impact

new_releases = Small Impact

* This is also dependent on partner marketing of the program

** Getting started, In-cart hosted solution requires lowest level of effort

The integration options presented have been widely adopted. However, there are many different ways ID.me's technology can benefit your platform. If you have a unqiue user experience or use case, please Contact Us to discuss how ID.me can help improve your ablitiy to verify user affiliation.

In Cart/Checkout Full Integration

ID.me’s standard full integration offers a seamless user experience that allows customers to easily apply group discounts at checkout. Since customers are trained to look for and apply discounts at checkout, this integration has proven to reduce cart abandonment and increase conversion rates by up to 4X. It has also shown to encourage customer loyalty and repeat purchases.

Ua example 01

In Cart/Checkout Hosted Integration

This solution creates a similar user experience as a full cart integration, but takes only a few minutes to install. Requiring minimal setup and developer resources, the Hosted Solution reduces the operational costs to launch a discount program.

Lenovo example 01

Within Account

Verify the user’s identity during the initial account creation process or within their existing account settings. Once an identity is tied to an account, partners are empowered to personalize the user experience. ID.me ensures that a customer’s information is tied to only one account, eliminating the risk of the same information being used to create duplicate accounts.

Mlbtv example 01

Single Sign On (SSO)

ID.me’s Single Sign-On integration allows customers to use their ID.me account to instantly access exclusive benefits, promotions and services. Each Single-Sign On account receives a unique user ID, eliminating the risk of duplicate accounts. Due to ID.me’s network approach, millions of eligible customers arrive pre-verified with an existing ID.me account.

Tdc example 01

Landing Page

Partners can create a customized experience with the Landing Page integration. This option allows partners to limit the exposure of their discount program while increasing customer loyalty. ID.me also passes valuable customer data back to the partner, empowering marketers to segment audiences in their CRM and retarget customers.

Medievaltimes example 01

In-Store

ID.me’s In-Store capabilities create a seamless in-store experience that removes the burden of determining customer eligibility from store employees. Verifying customers in-store protects customer data, increases customer loyalty, and expands the partner’s knowledge of their customer base—all the while reducing operational costs.

Academy example 01

Sample User Flows

The typical flow begins at one of our partner websites, where an end user may see an ID.me verification button during registration or in the checkout flow.

Step 1: Checking out at UnderArmour.com

Underarmour

When the user clicks a verification button, a popup window opens and they are taken to ID.me's website to verify their status in the selected group. Before verification begins the user must either sign in to an existing account or create a new account.

Step 2: Sign In to ID.me

Sign in

Step 3: Sign Up for ID.me

Sign up

Step 4: Group Verification

After authenticating, the next step is for the user to verify their affiliation with the selected group. They will be presented with a number of options to verify depending on the group. The following is an example of our verification.

Military verify
Responder verify
Government verify
Student verify
Teacher verify

Note: If a user has an existing ID.me Wallet account that is verified they will skip the verification screen.

After a successful verification, the user is presented with a screen where they are asked to consent to the release of their data to the partner. The user will see exactly what data fields the partner will have access to.

Consent

If consent is granted, the user will be taken back to the partner website at the redirect URI specified by the partner during application registration. At this point it is up to the partner to apply the business logic on their site to grant the end user access to the specified benefit.