OAuth Integration Guide

Upon application registration, you will immediately have access to the application details page which will list the client_id and client_secret needed to configure your OAuth client.

Overview

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 group affiliation 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. Access tokens expire 5 minutes after being issued.

The following diagram shows an overview of the OAuth flow. The "RP" in this diagram stands for "Relying Party", a.k.a the partner.

Getting an access token

In order to get an access_token you must do the following:

• Direct the user to ID.me's authorization endpoint
  • If the user is not signed in they will be asked to sign in or sign up.
  • After verifying their group affiliation the user will be asked to grant access to your app.
• After access is granted, the server will redirect the user to your redirect_uri and you can retrieve the access_token in one of two ways:
  • Server-side (authorization code flow): Take the provided code parameter in the redirect and exchange it for an access_token by POSTing the code to our access token request endpoint.
  • Client-side (access token flow): Instead of handling an authorization code, we include the access_token as a fragment (#) in the redirect. This method allows applications without any server component to receive an access_token with ease.