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:kba_replacement/covid/questionnaire
kba_replacement/covid/verify
fortified/covid/questionnaire
fortified/covid/verify
http://idmanagement.gov/ns/assurance/ial/2/aal/2/covid/questionnaire
http://idmanagement.gov/ns/assurance/ial/2/aal/2/covid/verify
|
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": "fortified/covid/verify"
}
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": "Malcolm"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Murphy"
},
{
"handle": "email",
"name": "Email",
"value": "malcolm.murphy@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "21219-4921"
},
{
"handle": "vaccination_status",
"name": "Vaccination Status",
"value": true
},
{
"handle": "vaccine_brand",
"name": "Manufacturer",
"value": "Pfizer"
},
{
"handle": "vaccine_date_1",
"name": "1st Dose",
"value": "2021-01-01"
},
{
"handle": "vaccine_date_2",
"name": "2nd Dose",
"value": "2021-02-01"
}
],
"status": [
{
"group": "covid_vaccine",
"subgroups": [
null
],
"verified": true
},
{
"group": "covid_vaccine",
"subgroups": null,
"verified": true
}
]
}
Requirements
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. |