OAuth | Public Benefits Recipient Verification

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

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: `pbr`
`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": "pbr"
}

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/userinfo?access_token=ACCESS_TOKEN"

Endpoint

https://api.id.me/api/public/v3/userinfo

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": "Majorie"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "Rodriguez"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "majorie.rodriguez@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "75462"
    },
    {
      "handle": "street",
      "name": "Street",
      "value": "9938 Sanjuanita Garden"
    },
    {
      "handle": "city",
      "name": "City",
      "value": "Conchastad"
    },
    {
      "handle": "state",
      "name": "State",
      "value": "South Dakota"
    },
    {
      "handle": "birthdate",
      "name": "Birth Date",
      "value": "1991-07-03"
    }
  ],
  "status": [
    {
      "group": "pbr",
      "subgroups": [
        "Medicaid"
      ],
      "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.

Documentation

Pbr - OAuth

OAuth 2.0 Integration

Step 1: Direct Users To Authorization Endpoint

Authorization Endpoint

Parameters

Supported values include:

Supported values include:

Supported values include:

Step 2: Receive The Authorization Code

Redirect URI with code example

Step 3: Exchange Authorization Code For Access Token

CURL Example

Endpoint

HTTP Request Method

Response Content Type

Parameters

Step 4: Obtain Access Token

Example Payload

Parameters

Step 5: Exchange Access Token For User Data

CURL Example

Endpoint

HTTP Request Method

Response Content Type

Parameters

Example Payload

Requirements

Errors

Parameters

Codes