Prerequisites

Before integrating the SDK, ensure your development environment meets the following requirements:

Android minimum API Level: 26 (Android 8.0)
Android Studio: Ladybug or later
Kotlin version: 2.1+
Chrome must be installed on the target device (required for Chrome Custom Tab)

Adding the SDK to your project

Ensure mavenCentral() is listed in your project-level settings.gradle.kts (or build.gradle) repositories block:

Example

1 dependencyResolutionManagement {
2     repositories {
3         mavenCentral()
4     }
5 }

Add the following to your app-level build.gradle.kts:

Example

1 dependencies {
2     implementation("com.idmelabs.auth:android-auth-sample-code:1.0.8")
3 }

Sync your Gradle project.

Required app integration steps

In your app’s AndroidManifest.xml, register IDmeRedirectActivity with an intent-filter matching your redirect URI scheme. This Activity captures the OAuth callback from the Chrome Custom Tab after verification completes.

Example

1 <activity
2     android:name="com.idme.auth.auth.IDmeRedirectActivity"
3     android:exported="true"
4     android:launchMode="singleTask"
5     android:theme="@android:style/Theme.Translucent.NoTitleBar">
6     <intent-filter>
7         <action android:name="android.intent.action.VIEW" />
8         <category android:name="android.intent.category.DEFAULT" />
9         <category android:name="android.intent.category.BROWSABLE" />
10         <data
11             android:scheme="yourapp"
12             android:host="idme"
13             android:path="/callback" />
14     </intent-filter>
15 </activity>

Replace yourapp with your app’s registered redirect scheme. The redirectURI you pass to IDmeConfiguration must match this exactly (e.g. yourapp://idme/callback).

Alternatively, use a manifest placeholder in your app-level build.gradle.kts to avoid hardcoding the scheme:

Example

1 android {
2     defaultConfig {
3         manifestPlaceholders["idmeRedirectScheme"] = "yourapp"
4     }
5 }

Initialization

Create an IDmeConfiguration with your client credentials and desired auth settings, then instantiate IDmeAuth:

Example

1 import com.idme.auth.IDmeAuth
2 import com.idme.auth.configuration.*
3 
4 val config = IDmeConfiguration(
5     clientId = "YOUR_CLIENT_ID",
6     redirectURI = "yourapp://idme/callback",
7     scopes = listOf(IDmeScope.MILITARY),
8     environment = IDmeEnvironment.PRODUCTION,
9     authMode = IDmeAuthMode.OAUTH_PKCE
10 )
11 
12 val idme = IDmeAuth(config, applicationContext)

Configuration reference

Parameter	Type	Default	Description
`clientId`	`String`	—	OAuth Client ID from ID.me
`redirectURI`	`String`	—	Registered redirect URI — must match your manifest
`scopes`	`List<IDmeScope>`	—	Community scopes to request
`environment`	`IDmeEnvironment`	`PRODUCTION`	`PRODUCTION` or `SANDBOX`
`authMode`	`IDmeAuthMode`	`OAUTH_PKCE`	`OAUTH_PKCE`, `OAUTH`, or `OIDC`
`verificationType`	`IDmeVerificationType`	`SINGLE`	`SINGLE` or `GROUPS`
`clientSecret`	`String?`	`null`	Required for `OAUTH` mode only

Auth modes

Mode	Description
`OAUTH_PKCE`	Recommended. OAuth 2.0 with PKCE. No client secret required.
`OAUTH`	Standard OAuth 2.0 Authorization Code. Requires `clientSecret`.
`OIDC`	OpenID Connect. Returns a signed ID token validated against ID.me’s JWKS.

Available scopes

Scope	Community
`MILITARY`	Active duty, veterans, and military families
`FIRST_RESPONDER`	First responders
`NURSE`	Nurses
`TEACHER`	Teachers and educators
`STUDENT`	Students

Common usage patterns

Starting the verification flow

Call login() from a coroutine, passing the current Activity. This opens a Chrome Custom Tab for the user to verify their community membership. The tab dismisses automatically when verification completes.

Example

1 viewModelScope.launch {
2     try {
3         val credentials = idme.login(activity)
4         // Verification complete — credentials contains access and refresh tokens
5         println(credentials.accessToken)
6         println(credentials.expiresAt)
7     } catch (e: IDmeAuthError.UserCancelled) {
8         // User dismissed the verification tab
9     } catch (e: IDmeAuthError) {
10         println("Verification failed: ${e.message}")
11     }
12 }

Retrieving community attributes (OAuth / PKCE)

Example

1 val attributes = idme.attributes()
2 for (attr in attributes.attributes) {
3     println("${attr.handle}: ${attr.value}")
4 }

Retrieving user info (OIDC)

Example

1 val userInfo = idme.userInfo()
2 println(userInfo.email)
3 println(userInfo.givenName)

Token management

The SDK stores credentials in EncryptedSharedPreferences and handles token refresh automatically:

Example

1 // Get valid credentials, refreshing if they expire within 60 seconds
2 val creds = idme.credentials(minTTL = 60)
3 
4 // Check expiry
5 if (creds.isExpired) {
6     // Token has expired
7 }
8 
9 if (creds.expiresWithin(300)) {
10     // Token expires within 5 minutes
11 }

Fetching available policies

Discover which verification policies your organization supports:

Example

1 val policies = idme.policies()
2 for (policy in policies.filter { it.active }) {
3     println("${policy.name} — scope: ${policy.handle}")
4 }

Logout

Example

1 idme.logout()

Clears all stored credentials and tokens from encrypted storage.

Error handling

All errors are thrown as IDmeAuthError, a sealed class:

Example

1 try {
2     val credentials = idme.login(activity)
3 } catch (e: IDmeAuthError.UserCancelled) {
4     // User dismissed the Chrome Custom Tab
5 } catch (e: IDmeAuthError.TokenExchangeFailed) {
6     println("Token exchange failed (${e.statusCode}): ${e.errorMessage}")
7 } catch (e: IDmeAuthError.StateMismatch) {
8     // OAuth state parameter mismatch — possible CSRF attempt
9 } catch (e: IDmeAuthError.NotAuthenticated) {
10     println("No stored credentials available")
11 } catch (e: IDmeAuthError) {
12     println(e.message)
13 }