Documentation | Server-Side | ID.me Developers

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 one organization for your company.
Register an application for each website property that will need access to KYC Account Opening data.
Contact partnersupport@id.me to enable the appropriate policies associated with verification and set up UAT/sandbox integrations.
Place our ‘Verify with ID.me’ button on your site to allow users to begin authentication and verification.
Once users complete verification 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

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. Client creates and records a secret key called code_verifier with every authorization request.
2. The code_verifier is transformed and referred to as the code_challenge.
3. Client sends the code_challenge along with the Authorization Request.
4. Server returns the authorization_code.
5. Client sends the authorization_code and the code_verifier to the Access Token Endpoint.
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.
unauthorized_client	The client is not authorized to use the requested response type.
redirect_uri_mismatch	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.

Was this section helpful?

Yes