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.
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 |
---|
https://api.id.me/oauth/authorize |
GET
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>
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 |
|
scope |
yes |
A parameter that defines the policy you are requesting permission to access. Possible values:
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 |
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.
Token Endpoint |
---|
https://api.id.me/oauth/token |
POST
application/json
Name | Description |
---|---|
code |
The authorization
|
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
|
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 |
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.
{
"access_token" : "a0b1c2d3f4g5h6i7j8k9l0m1n2o3p4q5"
"token_type" : "bearer"
"expires_in" : "300"
"refresh_token" : "e7c77fe1fd5ece9aaccb129f6dd39431"
"refresh_expires_in" : "604800"
"scope" : "kyc"
}
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 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.
Token Endpoint |
---|
https://api.id.me/oauth/token |
POST
application/json
Name | Description |
---|---|
refresh_token |
The
|
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
|
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 |
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.
{
"access_token" : "a0b1c2d3f4g5h6i7j8k9l0m1n2o3p4q5"
"token_type" : "bearer"
"expires_in" : "300"
"refresh_token" : "e7c77fe1fd5ece9aaccb129f6dd39431"
"refresh_expires_in" : "604800"
"scope" : "kyc"
}
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. |
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.
code_verifier
with every authorization request.
code_verifier
is transformed and referred to as the
code_challenge.
code_challenge
along with the Authorization Request.
authorization_code.
authorization_code
and the
code_verifier
to the Access Token Endpoint.
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.
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:
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. |
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. |