KYC Account Opening

Getting Started

To get started with an integration you’ll need to do the following.

  • Sign up for an ID.me developer account.
  • Register your organization.
  • Select which groups you would like to enable for verification.
  • Choose your platform to review the recommended integration options.
  • Place our ‘Verify with ID.me’ button on your site to begin testing authentication and verification.
  • Contact partnersupport@id.me to generate test credentials.
  • Once verification is complete at ID.me, the partner sends a request to ID.me’s API to retrieve user attributes.

By default, your application will be set up for OAuth. Upon registration, you will immediately have access to the application details page which will list the client_id and client_secret for your OAuth client.


Leveraging the ID.me IDP SAML service will vary depending on the product that is used to implement the federation relationship. Currently, we do not support creating SAML SP profiles automatically through the portal, please contact partnersupport@id.me for assistance in the process.


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.


The endpoint to be used for your app is available at the bottom of the app details page.

Endpoint

Authorization Endpoint
https://api.id.me/oauth/authorize

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

Groups endpoint

Parameters

Name Required Description
client_id yes The client identifier received during app registration. It is automatically generated and located in your application dashboard.
redirect_uri yes Where the user gets redirected after an authorizing an app. Set by the developer within the application dashboard.
response_type

yes

code

scope

yes

A parameter that defines the policy you are requesting permission to access.


Possible values:
  • kyc
Note: Your account must first be set up with policies to enable these scopes to be accepted.

Contact partnersupport@id.me if you receive errors regarding an invalid scope.

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.

Example
https://api.id.me/oauth/authorize?client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&response_type=code&scope=kyc&state=488e864b

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.


Redirect URI with code
http://example.com/callback?code=488e864b

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

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.

Example
curl -X POST -d "code=488e864b&client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&redirect_uri=[YOUR_REDIRECT_URI]&grant_type=authorization_code" https://api.id.me/oauth/token

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

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.


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

Token Endpoint
https://api.id.me/oauth/token

HTTP Request Method

POST

Response Content Type

application/json

Parameters

Name Description
refresh_token

The refresh_token you received in the Server-side (Explicit) Flow

client_id

The client identifier received during app registration. It is automatically generated and can be found in your application dashboard.

client_secret

A secret identifier received during app registration. It is automatically generated and can be found 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 required value for the Refresh Token Flow is refresh_token.

Example
curl -X POST -d "refresh_token=e7c77fe1fd5ece9aaccb129f6dd39431&client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&redirect_uri=[YOUR_REDIRECT_URI]&grant_type=refresh_token" https://api.id.me/oauth/token

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

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 group affiliation you are requesting permission to access.


OAuth PKCE

Proof Key for Code Exchange (PKCE) is a specification that adds additional parameters to OAuth 2.0 Authorization and Access Token Requests.


When implemenenting OAuth 2.0 on native applications Authorization Code Grants are susceptible to authorization code interception. Upon interception, malicous attackers have the ability to exchange the authorization code for an Access Token.


With every authroization request, PKCE allows the Client to create an encrypted secret key called code_verifier to be compared with the code_challenge associated with the request.

PKCE Protocol

  1. 1. Client creates and records a secret key called code_verifier with every authorization request.
  2. 2. The code_verifier is transformed and referred to as the code_challenge.
  3. 3. Client sends the code_challenge along with the Authorization Request.
  4. 4. Server returns the authorization_code.
  5. 5. Client sends the authorization_code and the code_verifier to the Access Token Endpoint.
  6. 6. Server verifies code_verifier before returning the tokens.

An attacker who intercepts the authorization code is unable to redeem it for an access token, as they are not in possession of the code_verifier.


Please contact us to enable PKCE support for your native integration.

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.

Waves