iOS Communities SDK


Prerequisites

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

  • iOS minimum deployment target: 15.0
  • Xcode: 16 or later
  • Swift: 5.9+

Adding the SDK to your project

1

In Xcode, go to File > Add Package Dependencies and enter the repository URL:

URL
1https://github.com/IDme/ios-auth-sample-code.git

Select version 1.0.0 or later and add IDmeAuthSDK to your target.

2

Alternatively, add the dependency directly to your Package.swift:

Example
1dependencies: [
2 .package(url: "https://github.com/IDme/ios-auth-sample-code.git", from: "1.0.0")
3],
4targets: [
5 .target(
6 name: "YourApp",
7 dependencies: ["IDmeAuthSDK"]
8 )
9]

Required app integration steps

1

Register a custom URL scheme in your app’s Info.plist so iOS can route the OAuth callback back to your app after verification:

Example
1<key>CFBundleURLTypes</key>
2<array>
3 <dict>
4 <key>CFBundleURLSchemes</key>
5 <array>
6 <string>yourapp</string>
7 </array>
8 </dict>
9</array>

The scheme must match the scheme portion of your redirectURI. For example, if your redirect URI is yourapp://idme/callback, register yourapp as the scheme.

Initialization

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

Example
1import IDmeAuthSDK
2
3let config = IDmeConfiguration(
4 clientId: "YOUR_CLIENT_ID",
5 redirectURI: "yourapp://idme/callback",
6 scopes: [.military],
7 environment: .production
8)
9
10let idme = IDmeAuth(configuration: config)

Configuration reference

ParameterTypeDefaultDescription
clientIdStringOAuth Client ID from ID.me
redirectURIStringRegistered redirect URI — must match your URL scheme
scopes[IDmeScope]Community scopes to request
environmentIDmeEnvironment.production.production or .sandbox
verificationTypeIDmeVerificationType.single.single or .groups
clientSecretString?nilOptional. Required by the policies endpoint if used.

Available scopes

ScopeCommunity
.militaryActive duty, veterans, and military families
.firstResponderFirst responders
.nurseNurses
.teacherTeachers and educators
.studentStudents

Common usage patterns

Starting the verification flow

Call login(from:) from an async context, passing a UIWindow as the presentation anchor. The SDK opens a system browser sheet (ASWebAuthenticationSession) for the user to verify their community membership. The sheet dismisses automatically when verification completes.

Example
1do {
2 let credentials = try await idme.login(from: window)
3 // Verification complete — credentials contains access and refresh tokens
4 print(credentials.accessToken)
5 print(credentials.expiresAt)
6} catch let error as IDmeAuthError where error == .userCancelled {
7 // User dismissed the verification sheet
8} catch {
9 print("Verification failed: \(error.localizedDescription)")
10}

Retrieving community attributes

Example
1let response = try await idme.attributes()
2
3for attr in response.attributes {
4 print("\(attr.handle): \(attr.value ?? "")")
5}
6
7for status in response.status {
8 print("\(status.group): verified=\(status.verified)")
9}

Token management

The SDK stores credentials in the Keychain and handles token refresh automatically:

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

Fetching available policies

Discover which verification policies your organization supports:

Example
1let policies = try await idme.policies()
2for policy in policies.filter({ $0.active }) {
3 print("\(policy.name) — scope: \(policy.handle)")
4}

Logout

Example
1idme.logout()

Clears all stored credentials and tokens from the Keychain.

Error handling

All errors are thrown as IDmeAuthError, a Swift enum conforming to LocalizedError:

Example
1do {
2 let credentials = try await idme.login(from: window)
3} catch let error as IDmeAuthError {
4 switch error {
5 case .userCancelled:
6 // User dismissed the system browser sheet
7 break
8 case .tokenExchangeFailed(let statusCode, let message):
9 print("Token exchange failed (\(statusCode)): \(message)")
10 case .stateMismatch:
11 // OAuth state parameter mismatch — possible CSRF attempt
12 break
13 case .notAuthenticated:
14 print("No stored credentials available")
15 case .refreshTokenExpired:
16 print("Session expired — user must log in again")
17 default:
18 print(error.localizedDescription)
19 }
20}