Welcome to ID.me for developers! If you are interested in integrating ID.me, you are in the right place. Here we will cover how to get started implementing ID.me.

OAuth 2.0 Integration

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. An access_token expire 5 minutes after being issued.


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

<div id="idme-verification">
  <p>Verify with ID.me as the primary action</p>
  <a href="https://api.id.me/oauth/authorize?client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&response_type=code&scope=military&state=488e864b">
    <img src="https://s3.amazonaws.com/idme/developer/idme-buttons/assets/img/verify.svg" height="50"/>
  </a>
  <p>
    <img src="https://developers.id.me/assets/buttons/lock-icon-a5b18fbb34d393a80967c08399786f95955ee818b693b97d3f37698e2bc113f2.svg" height="10"/>
    Verification by ID.me •
    <a href="https://www.id.me/about">What is ID.me?</a>
  </p>
</div>

Authorization Endpoint

The api.id.me/oauth/authorize endpoint is used begin an authorization to allow a user to authenticate and allow an organization get access to a user's verification credential.

Groups Endpoint

The groups.id.me endpoint is used to unify policies under one endpoint. Upon redirect, a user is prompted to self select which policy they would like to access, then proceed to the authorization endpoint.

ID.me Button Widget

The widget provides the easiest way to trigger the approprate endpoint, display ID.me's latest button asset and configure display settings that meeting ID.me's brand guidelines.

Parameters

Name Description
client_id The client identifier received during app registration. It is automatically generated and located in your application dashboard.
scope A parameter that defines the policy you are requesting permission to access.
Supported values include:
  • military
  • responder
  • student
  • teacher
  • government
  • employee
  • hospital_employee
  • nurse
  • medical
  • alumni
  • military_canada
  • responder_canada
  • student_canada
  • teacher_canada
  • government_canada
  • nurse_canada
  • doctor_canada
  • alumni_canada
  • redirect_uri Where the user gets redirected after an authorizing an app. Set by the developer within the application dashboard.
    response_type Determines the authorization type.
    Supported values include:
  • code
  • token
  • state 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.
    op An optional parameter that triggers.
    Supported values include:
  • signin
  • signup
  • Step 2: Receive The Authorization Code

    When the user completes the authorization process on ID.me, we will redirect the user to your redirect_uri with the authorization code parameter appended.

    Redirect URI with code example

    https://example.com/callback? code=488e864b

    Step 3: Exchange Authorization Code For Access Token

    Using the authorization code from the previous step, send a request to ID.me's Token Endpoint to retrieve the payload containing your access_token and refresh token each token's expiration can be found in the payload.

    CURL Example

    curl -X POST -d "code=488e864b&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&grant_type=authorization_code" https://api.id.me/oauth/token
    Endpoint
    https://api.id.me/oauth/token
    HTTP Request Method
    POST
    Response Content Type
    application/json

    Parameters

    Name Description
    code The authorization 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 application dashboard.
    grant_type The only supported value is currently authorization_code

    Step 4: Obtain Access Token

    Example Payload

    {
      "access_token": "a0b1c2d3f4g5h6i7j8k9l0m1n2o3p4q5",
      "token_type": "bearer",
      "expires_in": "300",
      "refresh_token": "e7c77fe1fd5ece9aaccb129f6dd39431",
      "refresh_expires_in": "604800",
      "scope": "military_canada"
    }

    Parameters

    Name Description
    access_token A credential that is used with every API call, so ID.me recognizes that you have authorization to make that request.
    token_type Represents how an access_token will be generated and presented for resource access calls.
    expires_in Describes the lifetime of the access_token in seconds.
    refresh_token Refresh tokens contain the information required to obtain a new access_token.
    refresh_expires_in Describes the lifetime of the refresh_token in seconds.
    scope Defines the policy you are requesting permission to access

    Step 5: Exchange Access Token For User Data

    Protected REST endpoints can be access by making HTTP requests 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.

    CURL Example

    curl -X GET "https://api.id.me/api/public/v3/attributes.json?access_token=ACCESS_TOKEN"
    Endpoint
    https://api.id.me/api/public/v3/attributes.json
    HTTP Request Method
    GET
    Response Content Type
    application/json

    Parameters

    Name Description
    access_token A credential that is used with every API call, so ID.me recognizes that you have authorization to make that request.
    callback 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.

    Example Payload

    {
      "attributes": [
        {
          "handle": "fname",
          "name": "First Name",
          "value": "Freeman"
        },
        {
          "handle": "lname",
          "name": "Last Name",
          "value": "Littel"
        },
        {
          "handle": "email",
          "name": "Email",
          "value": "freeman.littel@id.me"
        },
        {
          "handle": "uuid",
          "name": "Unique Identifier",
          "value": "d733a89e2e634f04ac2fe66c97f71612"
        },
        {
          "handle": "zip",
          "name": "Zip Code",
          "value": "82362"
        }
      ],
      "status": [
        {
          "group": "teacher",
          "subgroups": [
            "State-licensed/Certified PreK-12 Classroom Teacher"
          ],
          "verified": true
        }
      ]
    }
    Requirements

    Please follow the two steps outlined below. Note that you are responsible for ensuring that all implementations of the ID.me brand assets comply with accessibility requirements (example: Section 508 minimum color contrast requirements & WCAG guidelines). Visit https://webaim.org for more information.

    Step 1

    Verify your integration meets ID.me brand requirements and guidelines. For reference, please visit https://developers.id.me/brand-assets.

    Step 2

    Verify your integration makes an API request upon retrieving the access_token from ID.me.

    Step 3

    Verify all test credentials provided are generating the expected results based on configuration.

    Step 4

    Verify your platform digests and maps the verification data to the appropriate user and presents success messaging.

    Step 5

    Verify your ID.me application is in production mode and does not display "Sandbox Mode" to users.

    Errors

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

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