Overview

Using ID.me's verification technology, partners may target the following affinity groups with special offers or benefits on their platform.

  • Military - Troop ID
  • Students - Student ID
  • First Responders - Responder ID
  • Teachers - Teacher ID
  • Government Employees - Government ID

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

  • Sign up for an ID.me developer account.
  • Register an application for each website property that will need access to verification data.
  • Place one or more ID.me verification buttons on your site for each group you wish to target.
  • Once users complete the authentication/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.

Screenshot 1: Checking out at UnderArmour.com

Checkout ua

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.

Screenshot 2: Sign in to ID.me

Sign in

Screenshot 3: Sign up for ID.me

Sign up

The next step is for the user to verify their affiliation with the selected group. The user is given multiple options to verify. The following is an example of our military verification screen.

Screenshot 4: Military Verification

Verify military

Note that if a user has already verified their ID.me account, they will bypass 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 are passed to the partner.

Screenshot 5: User Consent

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 discount or benefit.

Note: The verification flow can include your company's branding. In the screenshots above, the green and white "ID" icon in the top right corner can be replaced with your logo.

Production Launch

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.

Onced you've successfully verified your application is working in sandbox mode you can request production access from the Applications edit page by clicking "Request Production Mode".

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

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.

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

HTTP Request Method

GET

Parameters

Name Required Description
client_id yes The client identifier received during app registration
redirect_uri yes Where the user gets redirected after an authorizing an app
response_type yes Must equal "code" the server-side flow, and "token" in the client-side flow.
scope yes A parameter that defines the group affiliation you are requesting permission to access. Possible values are: "military", "student", "responder", "government", or "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.

The endpoint to be used for your app is available at the bottom of the app details page. Please see the screenshot below for an example:

(screenshot coming soon)

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. This code is only valid for 5 minutes.

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

Error Response

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

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

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.

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.

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 your client id
client_secret your client secret
redirect_uri your redirect URI
grant_type The only supported value is currently authorization_code.

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 different 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

Step 2. Receive the access token in the URL fragment

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 the same error response as in the server-side flow.

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.

1. Attributes Endpoint

Each API call to the attributes endpoint will return the following data elements by default:

  • The user's verification status for the specified group (true or false)
  • If applicable, the specific sub-affiliation within the group such as Veteran or Retiree
  • A unique identifier for the user
  • The user's first name
  • The user's last name
  • The user's email
URI
https://api.id.me/api/public/v2/attributes.json?access_token=ACCESS_TOKEN
HTTP Request Method

GET

Response Content Type

application/json

Example Response
{ "id": "3ec867e9461580fb10779", "verified": true, "affiliation": "Service Member", "email": "IDme_test_user@example.com", "fname": "Test", "lname": "User", "zip": "22102" }

JSONP

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

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

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