KYC Account Opening

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.

Endpoint

HTTP Request Method

GET

Groups Endpoint

Instead of using the Authorization Endpoint, the Groups Endpoint can be leveraged to unify all groups under one "Verify with ID.me" button. When the "Verify with ID.me" is pressed, a user is prompted to self select which group they're a part of.

<span
  id='idme-wallet-button'
  data-scope='military,student'
  data-client-id='[YOUR_CLIENT_ID]'
  data-redirect='[YOUR_REDIRECT_URI]'
  data-response='code'>
</span>
<script src='https://s3.amazonaws.com/idme/developer/idme-buttons/assets/js/idme-wallet-button.js'></script>

Example

Parameters

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. This code is used to obtain an access token and is only valid for 5 minutes.

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 will receive an error response. See error examples here.

Step 3. Exchange the authorization code for an Access Token

Endpoint

HTTP Request Method

POST

Response Content Type

application/json

Parameters

Step 4. Obtain the 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. See error examples here.

Example Payload

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

Parameters

Refresh Token Flow

Refresh tokens carry the information necessary to get a new access token. A common use case includes getting a new access token after an old one has expired. Refresh tokens can also expire but are rather long-lived.

Step 1. Exchange the Refresh Token

HTTP Request Method

POST

Response Content Type

application/json

Parameters

Step 2. Obtain the new Access Token and Refresh Token

Using the refresh token from the previous step, send a request to ID.me's servers to retrieve the payload to obtain a new access token and refresh token. Each token's expiration can be found in the payload. See error examples here.

Example Payload

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

Parameters