Overview

Using ID.me's verification technology, partners may 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 Employees

Government ID

Getting Started

To get started with an integration you'll need to do the following.

  • Sign up for an ID.me developer account.
  • Register one organization for your company.
  • Register an application for each website property that will need access to verification data.
  • Contact partnersupport@id.me to setup the appropriate policies associated with the affinity groups you want to verifiy.
  • Place one or more ID.me verification buttons on your site for each group you wish to target.
  • Once users complete the verification flow at ID.me, send requests to ID.me's API to retrieve their group affiliation data.

You can reach us for support at any time by emailing partnersupport@id.me

API Terms of Use

Before you start using the API, we have a few guidelines that we'd like to tell you about. We encourage you to read the full API Terms of Use, but here are the bullet points:

  • ID.me users own their data.
  • ID.me is a user-centric, permissions based platform that requires explicit permission for each transmission of information from a user to a partner brand through ID.me.
  • You may not sell ID.me user data to third party sites.
  • You cannot replicate the core user experience of ID.me

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: Military 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 military verification.

Mil verify

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

Step 5: User Consent

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.

OAuth 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

Integration Overview

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.

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: 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.

Server-side (Explicit) Flow

ID.me supports both a full page redirect to the authorization endpoint as well as a popup window. Once you have registered an application, sample code and documentation will be available on the application details page. The ability to upload your company logo and customize the colors of the buttons on the ID.me screen are also available.

Step 1. Direct users to the authorization endpoint

The client app must send the user to the authorization endpoint in order to initiate the OAuth process. At the authorization endpoint, the user authenticates on the ID.me server and then grants or denies access to the app.

Authorization Endpoint
https://api.id.me/oauth/authorize?client_id= client-id &redirect_uri= redirect-uri &response_type= code &scope= scope &state= state
The endpoint to be used for your app is available at the bottom of the app details page. Please see the video below. Be sure the proper client_id , redirect_uri , response_type , and scope is in place.

HTTP Request Method

GET

Parameters

Name Required Description
client_id

yes

The client identifier received during app registration. It is automatically generated and located in your application dashboard.

redirect_uri

yes

Where the user gets redirected after an authorizing an app. Set by the developer within the appilcation dashboard.

response_type

yes

code

scope

yes

A parameter that defines the group affiliation you are requesting permission to access.


Possible values:
  • military
  • student
  • responder
  • government
  • teacher
Note: Your account must first be set up with policies to enable these scopes to be accepted.

Contact partnersupport@id.me if you don't see the policies configured for your application.

state

no

An optional parameter to carry through any server-specific state you need to, for example, protect against CSRF issues. This param will be passed back to your redirect URI untouched.

Step 2. Receive the redirect from ID.me

When the user completes the authorization process on ID.me, we will redirect the user to your redirect_uri along with a code parameter appended that you will use in the next step to obtain an access token. Retreive the authorization code in the URL fragment. This code is only valid for 5 minutes. It will look like so:


http://your-redirect-uri ?code=CODE


Simply grab the code off of the URL fragment and you’re good to go. If the user chooses not to grant access to your app, you’ll receive an error response. See error examples here.

Step 3. Direct users to the access token endpoint

The client app must send the user to the access token endpoint. At the access token endpoint, the user authenticates on the ID.me server and then grants or denies access to the app.

Access Token URI
https://api.id.me/oauth/token

HTTP Request Method

POST

Response Content Type

application/json

Parameters

POST the code along with the app identification parameters to our access token endpoint. Here are the required parameters:

Name Description
code

The exact code that you received in the previous step.

client_id

The client identifier received during app registration. It is automatically generated and located in your application dashboard.

client_secret

A secret identifier received during app registration. It is automatically generated and located in your application dashboard.

redirect_uri

Where the user gets redirected after an authorizing an app. Set by the developer within the appilcation dashboard.

grant_type

The only supported value is currently authorization_code.

Step 4. Obtain an Access Token

Using the access code from the previous step, send a request to ID.me's servers to obtain an access token. These tokens expire after 5 minutes.


Client-side (Implicit) Flow

If you’re building an app that does not have a server component (a purely javascript app, for instance), you’ll notice that it’s impossible to complete step three above to receive your access_token without also having to ship your client secret. You should never ship your client secret onto devices you don’t control. Then how do you get an access_token? Well the smart folks in charge of the OAuth 2.0 spec anticipated this problem and created the Implicit Authentication Flow.

Step 1. Direct users to the authorization endpoint

The only difference with the server-side flow is that the response_type is token.

Authorization Endpoint
https://api.id.me/oauth/authorize?client_id= client-id &redirect_uri= redirect-uri &response_type= token &scope= scope
The endpoint to be used for your app is available at the bottom of the app details page. Please see video below. Be sure the proper client_id , redirect_uri , response_type , and scope is in place.

HTTP Request Method

GET

Parameters

Name Required Description
client_id

yes

The client identifier received during app registration. It is automatically generated and located in your application dashboard.

redirect_uri

yes

Where the user gets redirected after an authorizing an app. Set by the developer within the appilcation dashboard.

response_type

yes

token

scope

yes

A parameter that defines the group affiliation you are requesting permission to access.


Possible values:
  • military
  • student
  • responder
  • government
  • teacher
Note: Your account must first be set up with policies to enable these scopes to be accepted.

Contact partnersupport@id.me if you don't see the policies configured for your application.

Step 2. Receive the redirect from ID.me

Once the user has authenticated and then authorized your application, we’ll redirect them to your redirect_uri with the access_token in the url fragment. It’ll look like so:


http://your-redirect-uri/ #access_token=TOKEN &token_type=bearer&expires_in=300


Simply grab the access_token off of the URL fragment and you’re good to go. If the user chooses not to grant access to your app, you’ll receive an error response. See error examples here.

Step 3. Obtain an Access Token

Using the access code from the previous step, send a request to ID.me's servers to obtain an access token. These tokens expire after 5 minutes.

REST API Endpoints

Clients access protected data by making API calls with the access token for a given user. The ID.me server will validate the access token to ensure it has not expired and that its scope covers the requested resource.

After getting a successful verification response from the API, you should apply business logic to unlock the benefit you are offering to the end user. From a user experience perspective, it is recommended that you store the verified status in the user's session to keep the experience consistent in case the page is refreshed, the back button is pressed, etc. By hiding or disabling the button that inititiates the API call, you can prevent duplicate calls being made.

Attributes Endpoint

JSON is the standard response type. If you're writing an AJAX application, require a JSONP response, and would like to wrap our response with a callback, all you have to do is specify a callback parameter with the API call.


URI Type
https://api.id.me/api/public/v2/attributes.json ?access_token=ACCESS_TOKEN JSON
https://api.id.me/api/public/v2/attributes.json ?access_token=ACCESS_TOKEN & callback=callbackFunction JSONP

HTTP Request Method

GET

Response Content Type

application/json

Errors

If the user denies the access request or if the request is invalid, the client will be informed using the following parameters added on to the redirect:

Parameters

Name Description
error

A single error code as described below.

error_description

A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.

error_uri

A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

Codes

Code Description
invalid_request

The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed.

invalid_client

The client identifier provided is invalid.

unauthorized_client

The client is not authorized to use the requested response type.

redirect_uri_mismatch

The redirection URI provided does not match a pre-registered value.

access_denied

The end-user or authorization server denied the request.

unsupported_response_type

The requested response type is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, or malformed.

JSON Payload

Example

{
  "id": "a1b2c3d4e5f6g7h8i9j0",
  "verified": true,
  "affiliation": "Service Member",
  "fname": Test,
  "lname": User,
  "email": "test.user@id.me",
  "uuid": "a1b2c3d4e5f6g7h8i9j0"
}

Values

The JSON payload contains the verification status and attributes of a user. It also can pass back valuable data that can be leveraged in your application.


Parameter Value Range
id

Unique to user

verified

true

false

affiliation

Troop ID - Service Member, Military Family, Military Spouse, Veteran, Retiree

Responder ID - EMT, Firefighter, Police Officer

Government ID - Federal, State, Local

Student ID - null

Teacher ID - null

fname

First name set by user

lname

Last name set by user

email

Unique to user

uuid

Unique to user

Production Overview

When you create an application it will initially be in sandbox mode. In sandbox mode you will have access to test data to ensure you have integrated with the ID.me platform properly. Once you've verified your application is working in sandbox mode you can request production access from your application's edit page by clicking "Request Production Mode". See the video below:

Production Launch Checklist

Client Libraries

ID.me has developed the following e-commerce platform extensions and libraries to ease the integration process.

Magento (PHP)

The official ID.me Magento plugin.

http://www.magentocommerce.com/magento-connect/troop-id-connect-4719.html

Demandware Link Cartridge

The official ID.me Demandware Link Cartridge.

https://s3.amazonaws.com/idme/developer/IDmeLinkCartridge-1.1.zip

Spree Commerce

An extension allowing any Spree store owner to offer promotions to verified members of ID.me

https://github.com/IDme/spree_idme

OmniAuth (Ruby/Rails)

Ruby gem that works with applications using OmniAuth .

https://github.com/IDme/omniauth-idme

PHP Web App

To view the full sample project visit Github

Step 1. Add dependencies

Add the oauth2-client dependency to your composer.json and install with php composer.phar install

{
    "require": {
        "league/oauth2-client": "^1.1"
    }
}

Step 2. Configure your client settings and secrets

  $provider = new \league\oauth2\client\provider\genericprovider([
      'clientid'                => 'YOUR_CLIENT_ID',
      'clientsecret'            => 'YOUR_CLIENT_SECRET',
      'redirecturi'             => 'YOUR_REDIRECT_URI',
      'urlauthorize'            => 'https://api.id.me/oauth/authorize',
      'urlaccesstoken'          => 'https://api.id.me/oauth/token',
      'urlresourceownerdetails' => 'https://api.id.me/api/public/v2/attributes.json'
  ]);

Step 3. Redirect the user to ID.me's OAuth 2.0 server

Generate the authorization endpoint URL

$authorizationUrl = $provider->getAuthorizationUrl();

Redirect the user to $authorizationUrl

header('Location: ' . filter_var($authorizationUrl, FILTER_SANITIZE_URL));
exit;

Step 4. Exchange the code for an access token

Use the getAccessToken method to exchange the authorization code for an access token

$accessToken = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code'], 'scope' => 'military'
]);

Step 5. Call ID.me's API

Use the access token to call ID.me's API and retrieve the user's attributes

$payload = $provider->getResourceOwner($accessToken)->toArray();

You can check the user's attributes via $payload['verified'] and $payload['affiliation']

Python Web App

To view the full sample project visit Github

Step 1. Add dependencies

Add the requests-oauthlib dependency to your requirements.txt and run pip install -r requirements.txt

requests-oauthlib

Step 2. Configure your client settings and secrets

client_id              = 'YOUR_CLIENT_ID'
client_secret          = 'YOUR_CLIENT_SECRET'
redirect_uri           = 'YOUR_REDIRECT_URI'
authorization_base_url = 'https://api.id.me/oauth/authorize'
token_url              = 'https://api.id.me/oauth/token'
attributes_url         = 'https://api.id.me/api/public/v2/attributes.json'
scope                  = ['YOUR_SCOPE_VALUE']

Step 3. Redirect the user to ID.me's OAuth 2.0 server

Generate the authorization endpoint URL

idme = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope)
authorization_url = idme.authorization_url(authorization_base_url)

Redirect the user to the authorization_url

redirect(authorization_url)

Step 4. Exchange the code for an access token

Use the fetch_token method to exchange the authorization code for an access token

token = idme.fetch_token(token_url, client_secret=client_secret, authorization_response=request.url)

Step 5. Call ID.me's API

Use the access token to call ID.me's API and retrieve the user's attributes

idme = OAuth2Session(client_id, token=token)
payload = idme.get('attributes_url').json()

You can check the user's attributes via payload['verified'] and payload['affiliation']

Mobile SDKs

ID.me Web Verify (iOS)

A library that verifies a user's group affiliation through a modal UIWebView. This library is open source and freely available to all.

https://github.com/IDme/ID.me-WebVerify-SDK-iOS

ID.me Web Verify (Android)

A library that verifies a user's group affiliation through a WebView activity. This library is open source and freely available to all.

https://github.com/IDme/ID.me-WebVerify-SDK-Android